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ABOUT THIS CHAPTER 


This chapter describes the File Manager, the part of the Operating System that 
controls the exchange of information between a Macintosh application and files. 
The File Manager allows you to create and access any number of files containing 
whatever information you choose. 


The changes to the File Manager are so extensive that the chapter has been 
completely rewritten. For most programmers, the changes are transparent and 
require no modification of code. All operations on the 64K ROM version of the 
File Manager are supported. 


This chapter also presents a set of new file access routines that support 
application execution in a shared environment. A shared environment can mean a 
number of workstations connected to a file server; it can also mean a 
multitasking operating system or a system program that allows sharing 
applications or data. The discussion in this chapter focuses on AppleShare™. 
This chapter describes how the old access modes are translated into the new 
ones, discusses some aspects of file access implementation in a shared 
environment, and presents the format of the routines. 


Reader's guide: Since virtually any application may someday find itself 
executing in a shared environment, all developers should 
have some understanding of the information in this chapter. 
Readers should be familiar with the following chapters from 
Inside Macintosh: 


e The AppleTalk Manager 
¢ The Device Manager 
« The Standard File Package 


Further information on Apple networking and file servers may be obtained from 


Inside AppleTalk, Section XI: AppleTalk Session Protocol (ASP) 
AppleTalk Filing Protocol, Version 1.1 

AppleShare User's Guide 

AppleShare Administrator's Guide 

AppleTalk Filing Protocol Engineering Notes 


eoeeee 
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ABOUT THE FILE MANAGER 


The File Manager is the part of the Operating System that handles communication 
between an application and files on block devices such as disk drives. (Block 
devices are discussed in the Device Manager chapter.) Files are a principal 
means by which data is stored and transmitted on the Macintosh. A file is a 
named, ordered sequence of bytes. The File Manager contains routines used to 
read from and write to files. 


Warning: Currently, only a startup volume with the AppleShare file located 
in its System Folder supports the File Manager extensions. Future 
versions of the File Manager may or may not support these calls. 


When the File Manager was originally designed, only three file-access modes were 
thought to be necessary: read/write, read only, and whatever's available 

(of the first two). These modes operated under a basic rule of file access 
known as "Single writer and/or multiple readers". In a world with file servers 
and multitasking systems, where more than one application might have access to a 
document simultaneously, this rule and these access modes are not sufficiently 
flexible. 


In addition to specifying the access required by the caller, the new access 
modes give the caller the ability to deny access to other users. The new modes 
are therefore known as deny modes. They operate by setting bits in the 
permissions byte instead of using a constant value as a message. The new access 
modes are implemented by ten new calls and one modified call (PBGetCatInfo) 
described later in this chapter. 


So that existing applications will work, the external file system used by 
AppleShare translates the old modes into the new. For the majority of 
applications, this translation will be sufficient. 


Volumes and the File Directory 


A volume is a piece of storage medium, such as a disk, formatted to contain 
files. A volume can be an entire disk or only part of a disk. A 3 1/2-inch 
Macintosh disk is one volume. Specialized memory devices, such as hard disks and 
file servers, can contain many volumes. The size of a volume also varies from 
one type of device to another. Macintosh volumes are formatted into chunks known 
as logical blocks, each able to contain up to 512 bytes. Files are stored in 
allocation blocks, which are multiples of logical blocks. 


Each volume has a file directory containing information about the files on the 
volume. With small volumes (containing only a few dozen files), a "flat" file 
directory organized as a simple, unsorted list of file names is sufficient. 
Volumes initialized by the 64K ROM have such a flat file directory. 


64K ROM note: The 128K ROM version of the File Manager supports all 
operations on flat file directories. 
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With the introduction of larger storage devices (several megabytes per volume) 
containing a large number of files (thousands per volume), the flat file 
directory proves inadequate, since an exhaustive, linear search of all the files 
is so time-consuming. A major feature of the 128K ROM version of the File 
Manager is the implementation of a hierarchical file directory (sometimes 
referred to as the file catalog), that significantly speeds up access to large 
volumes. 


The hierarchical file directory allows a volume to be divided into smaller units 
known as directories. Directories can contain files as well as other 
directories. Directories contained within directories are also known as 
subdirectories. 

The hierarchical directory structure is equivalent to the user's perceived 
desktop hierarchy, where folders contain files or additional folders. In the 64K 
ROM version of the File Manager, however, this desktop hierarchy was essentially 
an illusion maintained completely by the Finder (at considerable expense). The 
introduction of an actual hierarchical directory containing subdirectories 
greatly enhances the performance of the Finder by relieving it of this task. 


Figure 1 illustrates these two ways of organizing the files on a volume. 


flat file directory hierarchical file directory 


rl iz 


Figure 1—-Flat and Hierarchical Directories 


Figure 1—-Flat and Hierarchical Directories 


About Names 
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Volumes, directories, and files all have names. A volume name consists of any 
sequence of 1 to 27 printing characters, excluding colons (:). File names and 
directory names consist of any sequence of 1 to 31 printing characters, 
excluding colons. You can use uppercase and lowercase letters when naming 


things, but the File Manager ignores case when comparing names (it doesn't 
ignore diacritical marks). 


64K ROM note: The 64K ROM version of the File Manager allows file names 
of up to 255 characters. File names should be constrained 
to 31 characters, however, to maintain compatibility with 
the 128K ROM version of the File Manager. The 64K ROM version 
of the File Manager also allows the specification of a 
version number to distinguish between different files with 
the same name. Version numbers are generally set to 0, though, 
because the Resource Manager, Segment Loader, and Standard 
File Package won't operate on files with nonzero version 
numbers, and the Finder ignores version numbers. 


About Directories 


A few terms are needed to describe the relationships between directories on a 
hierarchical volume. Figure 2 shows what looks to be an upside-down tree; it's a 
sample hierarchical volume. 
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Figure 2-4 Hierarchical Yolume 
Figure 2—-A Hierarchical Volume 
eeeClick on the X-Ref button, and refer to Technical Notes #77 & #102.¢¢¢ 


ALL of the volume's files stem from the directory labeled MyDisk; this is the 
root directory and is none other than the volume itself. The name of the root 
directory of a volume is the same as the volume name. 


Note: The volume name, constrained to 27 characters, is the sole exception 
to the rule that directory names can be up to 31 characters long. 


Each directory, including the root directory, is a distinct, addressable entity. 
Each directory has its own set of offspring (possibly an empty set), which is 
those files or directories contained in it. For instance, the directory Letters 
has the files Dad and Geri as offspring, while the root directory contains the 
file MacWrite and the directories System Folder and Empty Folder. Borrowing a 
term from physics, the number of offspring is known as the directory's valence; 
for instance, the valence of the directory Correspondence is 2. Similarly, for a 
given file or directory, the directory immediately above it is known as its 
parent. The root directory is the only directory that doesn't have a parent. 
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When created, every directory is given a directory ID that's unique (and 
assigned sequentially) for any given volume. The root directory always has a 
directory ID of 2. In Figure 2, for instance, the directory Empty Folder has a 
directory ID of 26. The directory ID of a given offspring's parent is known as 
its parent ID; for example, the parent ID of the file Template is 21. 


About Volumes 


A volume can be mounted or unmounted. When a volume is mounted, the File Manager 
reads descriptive information about the volume into memory. For each mounted 
volume, part of this information is placed in a data structure known as a volume 
control block (described in detail in the section "Data Structures in Memory"). 


Ejectable volumes (such as the 3 1/2-inch disks) are mounted when they're 
inserted into a disk drive; nonejectable volumes (such as those on hard disks) 
are always mounted. Only mounted volumes are known to the File Manager, and an 
application can access information on mounted volumes only. When a volume is 
unmounted, the File Manager releases the information stored in the volume 
control block. 


A mounted volume can be on-line or off-line. A mounted volume is on-line as long 
as the volume buffer and all the descriptive information read from the volume 
when it was mounted remain in memory (about 1K to 1.5K bytes); it becomes off- 
line when all but the volume control block is released. You can access 
information on on-line volumes immediately, but off-line volumes must be placed 
on-line before their information can be accessed. When an application ejects a 3 
1/2-inch disk from a drive, the File Manager automatically places the volume 
off-line. Whenever the File Manager needs to access a mounted volume that's been 
placed off-line and ejected, the dialog box shown in Figure 3 is displayed, and 
the File Manager waits until the user inserts the disk named volName into a 
drive. 


| t Please insert the disk: 


A | ¥volName 


Figure 3-Disk-i witch Dialog 
Figure 3—Disk-Switch Dialog 


Note: This dialog is actually a system error alert, as described in 
the System Error Handler chapter. 


Mounted volumes share a common set of volume buffers, which is temporary storage 
Space in the heap used when reading or writing information on the volume. The 
number of volumes that may be mounted at any time is limited only by the number 
of drives attached and available memory. 
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64K ROM note: In the 64K ROM version of the File Manager, each mounted 
volume was assigned its own volume buffer. 


To prevent unauthorized writing to a volume, volumes can be locked. Locking a 
volume involves either setting a software flag on the volume or changing some 
part of the volume physically (for example, sliding a tab from one position to 
another on a 3 1/2-inch disk). Locking a volume ensures that none of the data on 
the volume can be changed. 


Each volume has a name that you can use to identify it. On-line volumes in disk 
drives can also be accessed via the drive number of the drive on which the 
volume is mounted; the internal drive is number 1, the external drive is number 
2, and any additional drives connected to the Macintosh will have larger 
numbers. In most routines, however, you'll identify a volume by its volume 
reference number, which is assigned to a volume when it's mounted. When 
accessing an on-line volume, you should always use the volume reference number 
or the volume name rather than a drive number, because the volume may have been 
ejected or placed off-line. Whenever possible, use the volume reference number 
(to avoid confusion between volumes with the same name). 


Note: In the case of specialized storage devices (such as hard disks) 
containing several volumes, only the first on-line volume can be 
accessed using the drive number of the device. 


About Files 


A file is a finite sequence of numbered bytes. Any byte or group of bytes in the 
sequence can be accessed individually. A byte within a file is identified by its 
position within the ordered sequence. 


There are two parts, or forks, to a file: the data fork and the resource fork. 
Normally the resource fork of an application file contains the resources used by 
the application, such as menus, fonts, and icons, and also the application code 
itself. The data fork can contain anything an application wants to store there. 
Information stored in resource forks should always be accessed via the Resource 
Manager. Information in data forks can only be accessed via the File Manager. 
For simplicity, "file" will be used instead of "data fork" in this chapter. 


The size of a file is limited only by the size of the volume it's on. Space is 
allocated to a file in allocation blocks (multiples of 512 bytes). Two numbers 
are used to describe the size of a file. The physical end-of-file is the number 
of bytes currently allocated to the file; it's 1 greater than the number of the 
last byte in its last allocation block (since the first byte is byte number 0). 
The logical end-of-file is the number of those allocated bytes that currently 
contain data; it's 1 greater than the number of the last byte in the file that 
contains data. For example, given an allocation block size of two logical blocks 
(that is, 1024 bytes), a file with 50 bytes of data has a logical 

end-of-file of 50 and a physical end-of-file of 1024 (see Figure 4). 
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Figure 4—Logical and Physical End-of-File 
Figure 4—Logical and Physical End-of-File 


The File Manager maintains a current position marker, called the mark, to keep 
track of where it is in the file during a read or write operation. The mark is 
the number of the next byte that will be read or written; each time a byte is 
read or written, the mark is moved. 


When, during a write operation, the mark reaches the number of the last byte 
currently allocated to the file, another allocation block is added to the file. 


You can read bytes from and write bytes to a file either singly or in sequences 
of unlimited length. You can specify where each read or write operation should 
begin by setting the mark; if you don't, the operation begins at the byte where 
the mark currently points. You can find the current position of the mark by 
calling GetFPos. You can set the mark before the read or write operation with 
SetFPos; you can also set it in the Read or Write call itself. 


You can move the logical end-of-file to adjust the size of the file (such as 
after a resource file has been compacted); when the logical end-of-file is moved 
to a position more than one allocation block short of the current physical end- 
of-file, the unneeded allocation block will be deleted from the file. You can 
also increase the size of a file by moving the logical-end-file past the 
physical end-of-file. 


A file can be open or closed. An application can perform only certain 
operations, such as reading and writing, on open files; other operations, such 
as deleting, can be performed only on closed files. 


Your application can lock a file to prevent unauthorized writing to it. Locking 
a file ensures that none of the data in it can be changed; this is the same as 
the user-accessible lock maintained by the Finder. 


When a file is opened, the File Manager reads useful information about the file 
from its volume and stores it in a data structure known as a file control block. 
The contents of the file control block (described in detail in the section 

"Data Structures in Memory") are used frequently and can be obtained with the 
function GetFileInfo. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 « Apple Computer 
THE FILE MANAGER e 11 of 150 


When a file is opened, the File Manager creates an access path, a description of 
the route to be followed when accessing the file. The access path specifies the 
volume on which the file is located and the location of the file on the volume. 
Every access path is assigned a unique path reference number (a number greater 
than 0) that's used to refer to it. A file can have multiple access paths open; 
each access path is separate from all other access paths to the file. 


Each file has open permission information, which indicates whether data can be 
written to it or not. When you open a file, you request permission to read or 
write via an access path. You can request permission to read only, write only 
(rarely done), or both read and write. There are two types of read/write 
permission—exclusive and shared. Applications will generally want to request 
exclusive read/write permission. If an access path requests and is granted 
exclusive read/write permission, no other access path will be granted permission 
to write (whether write only, exclusive read/write, or shared 

read/write). 


A second type of read/write permission allows multiple access paths to be open 
for writing. If you'll be using only a portion, or range, of a file, you can 
request shared read/write permission. With shared read/write permission, the 
application must see to it that the file's data integrity is preserved. Before 
writing to a particular range of bytes, you need to "lock" it so that other 
access paths cannot write to that range at the same time. In the meantime, other 
access paths opened with shared read/write access can lock and write to other 
parts of the file. 


The shared read/write permission has no utility on a single Macintosh; this 
permission is intended for, and will be passed by, external file systems, where 
multiple read/write operations are performed. 


Note: If an access path is open with shared read/write permission, 
no access path can be granted exclusive read/write access. 


64K ROM note: Shared read/write permission is not implemented in the 
64K ROM version of the File Manager. 


If the file's open permission doesn't allow I/O as requested, a result code 
indicating the error is returned. 


Each access path can move its own mark and read at the position it indicates. 
All access paths to the same file share common logical and physical end-of-file 
markers. 


When an application requests that data be read from a file, the File Manager 
reads the data from the file and transfers it to the application's data buffer. 
Any part of the data that can be transferred in entire 512-byte blocks is 
transferred directly. Any part of the data composed of fewer than 512 bytes is 
also read from the file in one 512-byte block, but placed in temporary storage 
Space in memory. Then, only the bytes containing the requested data are 
transferred to the application. 


When an application writes data to a file, the File Manager transfers the data 
from the application's data buffer and writes it to the file. Any part of the 
data that can be transferred in entire 512-byte blocks is written directly. Any 
part of the data composed of fewer than 512 bytes is placed in temporary storage 
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Space in memory until 512 bytes have accumulated; then the entire block is 
written all at once. 


Note: Advanced programmers: The File Manager can also read a continuous 
stream of characters or a line of characters. In the first case, 
you ask the File Manager to read a specific number of bytes: When 
that many have been read or when the mark has reached the logical 
end-of-file, the read operation terminates. In the second case, 
called newline mode, the read will terminate when either of the 
above conditions is met or when a specified character, the newline 
character, is read. The newline character is usually Return (ASCII 
code $Q0D), but it can be any character. Information about newline 
mode is associated with each access path to a file, and can differ 
from one access path to another. 


Normally the temporary space in memory used for all reading and writing is the 
volume buffer, but an application can specify that an access path buffer be used 
instead for a particular access path (see Figure 5). 


— access path buffer — 
Tile at 


— volume buffer 
date butter — 


tile "B iT) 
— access path buffer —s 


Figure 5—Buffers for Transferring Data 


application's 


Figure 5-Buffers for Transferring Data 


Warning: You must lock any access path buffers of files in relocatable 
blocks, so their location doesn't change while the file is open. 
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OVERVIEW OF THE NEW FILE ACCESS METHODS 


This overview first describes the new access modes and how they might be used, 
and then how the old permissions are translated into the new. 


Opening Files 


The combination of access and deny requests in the new open calls creates four 
opening possibilities: browsing, exclusive access, single writer with multiple 
readers, and multiple writers. The best way to open a file depends on how the 
application is going to use it. Figure 6 charts the opening possibilities, 
including whether range locking is needed. (Range locking is described later in 
this chapter. ) 


browsing only none allowed 


exclusive access read yrite 


fone ata thine) deny readideny write 


single writer, read writer 
multiple readers deny wiite 


shared readwrite 
Pmnaney Writers) 


Figure 6-—Opening Files 
Figure 6—Opening Files 
Browsing 


Browsing is traditional read-only access. Browsing access permits multiple 
readers but no writers. Browsing access is useful for common files, such as help 
files, configuration files that don't often change, and dictionaries. 

Developers may wish to add a "Browse Only" checkbox to the SFGetFile dialog, so 
that the user may explicitly open a file in this manner. 


Note that the new deny flags take into account both existing access paths to a 
file and future attempts to open new paths. For example, if you attempt to open 
a file for browsing (read/deny-write permission), your call will succeed only if 
no write access paths currently exist to the file. Also, all future attempts to 
open the file with write access will fail (with a message that you already have 
a read/deny-write path) until you close the first read/deny-write path. 
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Exclusive Access 


This is the access mode that most unshared-data applications will use. (Most 
existing applications use fsCurPerm permissions, which are translated to 
exclusive access if it's available, as described below.) An exclusive-access 
open call will succeed only if there are no existing paths to the file. All 
future attempts to establish access paths to the file will be denied until the 
exclusive-access path is closed. 


AppleShare note: an exclusive-access open call will fail if you try to 
open a path to a file in a folder to which you do not 
have both "see files" and "make changes" privileges. 
In such a case, you could offer the user the choice of 
Opening a browse-only copy of the file, and try again 
using browsing access. Or you could attempt browsing 
access as soon as exclusive access fails, to avoid 
offering a choice that won't work. If the browsing 
access fails, report that the file cannot be opened; 
if it succeeds, offer the user the browse-only file. 


Single Writer, Multiple Readers 


This access method allows additional users to gain read-only access to browse a 
document being modified by the initial writer. The writer's application is 
responsible for range-locking the file before writing to it, to protect the 
readers from reading when the file is inconsistent. Likewise, the reader's 
application must explicitly check for errors in reading the file, to warn the 
user that the file was in the process of being updated and to try again later. 


Single writer, multiple readers is a step toward shared data, one that may be 
easy to accomplish for existing applications, especially those that are memory 
based. (A memory-based application is one that, when it opens a document, reads 
the entire document into memory. Note that it should not close the document's 
file, as this could lead to checkout problems, as described below under "Network 
Programming Guidelines". ) 


Shared Access 


Shared access should be used by an application that supports full multi-user 
access to its documents. Range locking is needed by each user's application to 
prevent other users from accessing information undergoing change. Each user 
must check for and handle errors resulting from other users' access. Some 
applications may prefer to use a semaphore to flag records in a document as 
checked out, rather than using range locking exclusively. 


Shared access is uSually designed into an application. It is not easy to modify 
an existing application to support full multi-user access to documents, except 
for memory-based applications, as discussed above. 


Translation of Permissions 
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AppleShare uses the deny-mode permissions exclusively. So that old applications 
will work, the external file system used by AppleShare (on each workstation) 
translates the classic permissions into the new permissions. 


To keep applications from damaging each other's files, the basic rule of file 
access (in translating permissions for AppleShare volumes) was changed to 
"single writer OR multiple readers, but not both." Because of this change, two 
applications cannot both have access to the same file unless both are read only; 
this eliminates the danger of reading from a file when it is inconsistent. 


Note: This change in the basic rule currently applies only to AppleShare 
volumes. Should a future version of the File Manager incorporate 
this change for local volumes, then an application expecting to get 
more than one path to a file (with at least one read/write) will fail. 


Figure 7 shows how the classic permissions described in the File Manager are 
translated into the new deny-mode permissions. 


Bhndand HFS Permissions DewsMode Permissions 


fsEGWrFerm [read write) exclusive (readlwriteldeny reabideny write) 
EeWrPerm [write only] oF 
felurFerm [whatever's available browsing [readideny write] 


fsRdWrShPerm [shared readiwrite) | Shared [readwriteldeny none] 


Figure 7-Access Mode Translations 
Figure 7—-Access Mode Translations 


FsRdPerm acts as you would expect: browsing access is achieved if there is no 
existing write access path to the file. 


The or in the middle translations means that if the call cannot be completed 
successfully with exclusive access, it is automatically retried using browsing 
access. 


For fsCurPerm, this is also what you'd expect: "whatever's available" has always 
meant "read/write if you can, otherwise, read only". The deny portions of the 
translation are important for enforcing the updated basic rule of file access: 
if there's an existing read or write access path to a file being opened with 
fsCurPerm, the first set of permissions will fail; the second set, browsing 
access, will then succeed only if there is no existing write access path to the 
file. 


Both fsRdwWrPerm and fsWrPerm (which has always been translated into fsRdWrPerm, 
since write-only access has little utility) are also retried as read-only, to 
Simulate the case where a file is being opened from a locked disk. Elsewhere, 
this chapter points out that fsRdwrPerm is granted even if the volume is locked, 
and that an error won't be returned until a PBWrite (or SetEOF or PBALLlocate) 
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call is made. The same is now true for a read-only folder on an AppleShare 
volume. (An exception is that if you eject a disk, you can then write to an 
open file on it; changing access privileges of a folder does not change the 
access established for an open path to a file in that folder.) 
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THE SHARED ENVIRONMENT 


A file server such as AppleShare allows users to share data, applications, and 
disk storage over a network. A file server is a combination of a computer, 
special software, and one or more large-capacity disks attached to other 
computers via a network. In the file server context, the other computers are 
known as workstations. The computer network allows communication between the 
file server and the workstations. Users have easy access to programs, data, and 
disk storage provided by the file server. 


AppleShare 


The server application available from Apple Computer is AppleShare. Explanation 
of the AppleShare file server environment should provide parallels for other 
shared environments. 


eeeClick on the X-Ref button, and refer to Technical Notes #165 & #216.¢+¢« 


Each hard disk attached to the server's computer is called a file server volume. 
A selected server volume will appear on the workstation's desktop as an icon and 
can be used just like any Macintosh disk. 


Access to the information contained in folders on the disk can be controlled by 
use of access privileges. In the AppleShare file server environment, access 
privileges control who has what kind of access to the contents of the folders 
contained on a volume. The access privileges are assigned on a folder-by-folder 
basis. A folder may be kept private, shared by a group of registered users, or 
shared with all users on the network. 


New users are registered, given passwords, and organized into groups. Users can 
belong to more than one group. Information about users and groups is stored in 
a data base on the server and is used to determine the access privileges the 
user or group has when they access an object on the server. The owner of a 
folder specifies that folder's access privileges for the following user 
categories: 


* Owner—the user who owns the folder (or who currently holds ownership) 

* Group—any group established by the AppleShare administrator (folders 
have only one group designation per folder) 

e Everyone—every user who has access to the file server (registered 
users and guests) 

e See Folders—see other folders in the folder 

e See Files—see the icons and open documents or applications in that 
folder as well 

e Make Changes—create, modify, rename, or delete any file or folder 
contained in the particular folder (Note: folder deletion requires 
other privileges as well.) 


An extensive discussion of access privileges can be found in the AppleShare 
User's Guide. 
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Resource Availability 


The availability of resources in a network or shared environment cannot be 
assumed. Certain file system operations taken for granted in a single-user 
environment must be monitored to ensure their successful completion, and 
appropriate error messages should be returned to the user if they fail. Some 
examples of failure are 


¢ a file read or write fails because the file has been removed, the 
file server has been shut down, or a break in the network has occurred 

« creation of a file on the server fails due to an existing duplicate 
name that is invisible to the user (it's in a folder to which the user 
does not have search access) 

¢ a file cannot be opened for use because another user has already opened 
the file or the user does not have the proper access privileges 


Preflighting system operations becomes important in the shared environment. 
Preflighting, a term derived from the careful world of aviation, means checking 
the availability of a resource before you attempt to use it. For example, if an 
application creates temporary files, the application should check to see if the 
names it gives to the temporary files already exist. If the name already 
exists, the application can then give the temporary files other names or warn 
the user of the impending problem. This example is especially relevant for 
computers attached to a network because file storage may not be local to the 
computer. 


Sharing 
Sharing may mean sharing both data and the application itself: 


¢ An example of data file sharing would be a project schedule that would 
be read by many users simultaneously but could be updated by only one 
user at a time. Simultaneous updates to such a file must be prevented 
in order to protect the data. 

e An example of application file sharing would be a word processor shared 
as a read only file among many users. A correctly written application, 
with a proper site license, would allow many users to use the same copy 
of the application at the same time. 


Data files may be shared at the file or subfile level. The latter would be 
appropriate for applications such as data bases and spreadsheets in which 
several parts of the file could be updated by users simultaneously, but each 
part of the file can be updated by only one user at a time. 


Range Locking 


Range locking is available through the PBLockRange function ( LockRng macro) 
described in elsewhere in this chapter. By using byte-range locking 


* you can lock and unlock ranges within a file at any time while you 
have it open 
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* you can keep other users from reading from or writing to a range 
e all range locks set by you are removed automatically when you close 
the file 


The LockRng call locks a range of bytes in an open file opened with shared 
read/write permission. Calling LockRng before writing to the file prevents 
another user from reading from or writing to the locked range while you are 
making your changes. 


On a file opened with a shared read/write permission, LockRng uses the same 
parameter block (HParamBlockRec) as both the Read and Write calls; by calling it 
immediately before Read or Write, you can use the information present in the 
parameter block for the Read or Write call. When calling LockRng, the ioPosMode 
field of HParamBlockRec specifies the position mode; bits 0 and 1 indicate how 
to position the start of the range. 


When your application finishes using the range, be sure it calls UnlockRng to 
free up that portion of the file for other users. Since the ioPosOffset field 
is modified by the Read and Write calls it must be set up again before making an 
UnlockRng call. 


When updating a particular record and that update affects other records within 
the file, first determine the range of bytes affected by the updated 
information. Then call LockRng to lock out any other user from accessing this 
range of data. If the lock request succeeds, the required changes to the data 
can be made. Then release the lock and make the data available to other users 
again. If the lock fails, several retries should be done. After several 
unsuccessful retries, an error message could be issued to indicate that the file 
is busy and the user should try again later. 


To append data to a file, lock a range including the logical end-of-file and the 
last possible addressable byte of the file ($7FFFFFFF-Hex), and then write to 
that range. This actually locks a range where data does not exist. Practically 
speaking, locking the entire unused addressable range of a file prevents another 
user from appending data until you unlock it. 


To truncate a file, lock the entire file, truncate the data, and then unlock the 
file. This will prevent another user from using a portion of the file while you 
are in the process of truncating it. 


Sharing Applications 


The shared environment may involve not only applications that allow multiple 
access to a file, but applications that themselves have multiple users. Some 
definitions may help sort this out: 


¢ Single-user (private data) applications allow only one user at a 
time to make changes to a file. 

¢ Multi-user (shared data) applications allow two or more users to 
concurrently make changes to the same file. 

e Single-launch applications allow only one user at a time to launch 
and use a single copy of the application. 

e Multi-launch applications allow two or more users at a time to 
launch and use a single copy of the application. 
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When single-user and multi-user are seen as describing data file sharing modes 
and single-launch and multi-launch describe the launching characteristic of the 
applications, four categories of network applications emerge, as shown in Figure 
8. 
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Figure §-Sharing Applications 
Figure 8—-Sharing Applications 


multi-user application needs to 


Lock records correctly while they are being modified. 
coordinating multiple writers to a single document can be accomplished 
by keeping the document open while it is in use and by using an open 
mode in the file system that specifically allows subsequent users of 


the document write access. 
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Include an update mechanism so that all users of a document receive 


updates when a record is changed. 


Use byte-range locking to permit only one writer in a byte range at 


a time. 


multi-launch application needs to 


Use ResEdit or FEdit to set the multi-launch or shared bit in the 


application's finder information. 


Consider limiting the total number of concurrent users of a given 


copy of the application. 
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Limiting the 


number of concurrent users requires that the application implement 


some method to count the users as they launch and quit the application. Counting 
can become complex; for example, counting temporary files is a workable 
approach, but the temporary files may not all be in the same place and may in 
fact be in the user's boot volumes. Counting temporary files would also require 
checking whether or not the temporary files in existence were really in use or 
merely the remnants of a user crash. 


One method to make things easier for the programmer is to require that a multi- 
launch application be able to create temporary files in the folder containing 
the application. You would, of course, have to document this so users would 
know that the application could not be launched from a read-only folder. 


Shared Environment Guidelines 


This section 
environment. 


contains some do's and don't's for developers working in a network 
Keep in mind that for most applications, the translated standard 


permissions will work fine. 


Things to Do 


1. If using the new calls, try them first. 


Structure your code such that you try the new open calls first, then 
check to see if paramErr is returned. A paramErr indicates that the 
file does not reside on a server volume. If that is the case, make 
the equivalent old style open call. Attempts to make the new calls 
specifying a local (non-AppleShare) volume will return a paramErr 
indicating that the local file system does not know how to handle 
the call. 


2. Inform the user what access was granted during the open process. 


Shared 
errors 


environment applications should respond appropriately to 
returned by the file system. A more precise error reporting 


mechanism is used to communicate between the file server and an 
application program running in a workstation. Applications should 
be prepared to respond to this error reporting mechanism correctly. 


3. Use the Scrap Manager to access the Scrapbook. 


Don't implement your own scrap mechanism. Use the ROM Scrap Manager 
so that resources in the scrap can be shared among applications. 


4. Keep program segmentation swapping to a minimum. 


The effect of program segmentation swapping is exaggerated when the 
application is launched from the file server, because segments are 
dynamically swapped in over the network. This can reduce the 
performance of the file server. 


Things to Avoid 


1. An application should not write to itself (either to data or to 
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resource forks). 


Applications should not save information by writing into their own 
file. When information specific to one user is saved in the the 
application's own file and that application is shared by two or more 
users, information owned by the first user may be overwritten by the 
second user, and so on. 


Multi-user applications should not use the Resource Manager to 
structure their data in a resource fork. 


The Resource Manager assumes that when it reads the resource map into 
memory (during OpenResFile), it will be the only one modifying that 
file. If two write-access paths existed to a resource fork, neither 
would have any way of notifying the other that the file had changed 
(and in fact, no way to reread the map). If your application uses 
resource files for document storage, you cannot share data (for 
multi-user access); if you want to create a multi-user or multi- 
launch version of your application you must find another way to 

store your data. 


Don't close a file while in the process of making changes to its contents. 


An application that opens a file, reads the file's contents into memory, 
and then closes the file, has checked out a copy of the file. After the 
file is closed, another user can open the file, read the contents of the 
file into memory, and then close it. Two copies of the file are now 
checked out to two different users. Each user, after changing the 
checked-out copy of the file, may decide to save the changes to the 
Original file: user one opens the file and writes the changes back 

into the original and closes the file, then user two does the same thing. 
The second user's write operation wipes out the first. Neither user is 
aware of what has happened and neither has a way of finding out. 


Applications should keep the file open while in use. This will prevent 
other users from obtaining an access path and modifying the file while 
it's currently open. 


Don't give temporary files fixed names. 


Many programs that create and open temporary files give them fixed 
names. If such an application is shared by many users, the program 

may attempt to create temporary files with duplicate names. One 
solution is not to create any temporary files on disk, holding all 
information in memory. Another is to save them in the System Folder 

of the user's boot volume (startup disk) which is usually available 

for the System file writing. This solution is not perfect, however, 
since a person's boot volume may be a disk with extremely Limited space. 


Do not directly examine or manipulate system data structures, such as 
file control blocks (FCB) or volume control blocks (VCB), in memory. 


Use File Manager calls to access FCB and VCB information. 


When the application directly examines the list of data structures 
related to volumes that are currently mounted without using the 
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appropriate calls to the File Manager, it is possible that these 
structures will not accurately reflect the structure of the data on 
file server volumes. 


To give the file system the opportunity to update information, use 
GetVolInfo to determine volume information and GetFCBInfo to determine 
open file information. 

The Allocate function is not supported by AppleShare. 


Instead, use SetEOF to extend a file by setting the logical end-of-file. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 « Apple Computer 
THE FILE MANAGER e 24 of 150 


USING THE FILE MANAGER 


This section outlines the routines provided by the File Manager and explains 
some basic concepts needed to use them. The actual routines are presented later 
in the chapter. 


The File Manager is automatically initialized each time the system starts up. 


You can call most File Manager routines via three different methods: high-level 
Pascal calls, low-level Pascal calls, and assembly language. The high-level 
Pascal calls are designed for Pascal programmers interested in using the File 
Manager in a simple manner; they provide adequate file I/0 and don't require 
much special knowledge to use. The low-level Pascal and assembly-language calls 
are designed for advanced Pascal programmers and assembly- language programmers 
interested in using the File Manager to its fullest capacity; they require some 
special knowledge to be used most effectively. 


Note: The names used to refer to File Manager routines in text (as opposed 
to in particular routine descriptions) are actually the assembly- 
language macro names for the low-level routines, but the Pascal 
routine names are very similar. 


Hierarchical Routines 
eeeClick on the X-Ref button, and refer to Technical Notes #44 & #77.¢+¢e 


Many new routines are introduced in the hierarchical version of the File 
Manager; they can be divided into two groups. These routines are used primarily 
by the File Manager itself. 


Routines in the first group are slight extensions of certain basic File Manager 
routines that allow the specification of a directory ID in addition to the other 
parameters; in certain cases they set or obtain additional information. These 
specialized routines have the same names as their general-purpose counterparts, 
but preceded by the letter "H". For instance, the routine HOpen is identical to 
the Open call except that it allows the specification of a directory ID. The 
routines in this first group are: HOpen, HOpenRF, HRename, HCreate, HDelete, 
HGetFileInfo, HSetFileInfo, and HGetVInfo. The calls in this group will work 
with the 64K ROM version of the File Manager, but most applications will never 
need to use them. 


The second group of hierarchical routines consists of calls that perform 
Operations unique to the hierarchical file directory. The routines in this group 
are: SetVolInfo, LockRng, UnlockRng, DirCreate, GetCatInfo, SetCatInfo, 
CatMove, OpenwD, CloseWD, GetWDInfo, and GetFCBInfo. 


Warning: Using any of the routines in this second group on a Macintosh 
equipped only with the 64K ROM version of the File Manager will 
result in a system error. Using them on a flat volume will have 
no effect on "folders" and will result in File Manager errors. 
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In general, you will want your application to be independent of any particular 
version of the File Manager. The benefits of the hierarchical file system are 
transparent to your application and do not require use of the hierarchical 
routines. You may, however, want to use the hierarchical routines under certain 
circumstances. One way of determining whether the hierarchical version of the 
File Manager is present is to check which version of the ROM is running by 
calling the Operating System Utilities procedure Environs. 


RAM-based hierarchical versions of the File Manager may also be encountered, 
however; a better way of determining which version of the File Manager is 
running is to examine the contents of the global variable FSFCBLen. Located at 
address $3F6, this variable is a word (two bytes) in length; it contains a 
positive value if the hierarchical version of the File Manager is active or -1 
if the 64K ROM version of the File Manager is running. You could test the value 
of this global variable in the following way: 


eeeClick on the X-Ref button, and refer to Technical Note #66.¢*ee 
CONST FSFCBLen = $3F6; {address of global variable} 
VAR HFS: “INTEGER; 


HFS := POINTER(FSFCBLen) ; 
IF HFS* > 0 
THEN 
BEGIN 
{we're running under the hierarchical version} 
END; 
ELSE 
BEGIN 
{we're running under the 64K ROM version} 
END; 


Even after determining that the hierarchical version is running, you'll still 
need to check that a mounted volume is hierarchical by calling the HGetVInfo 
function. 


Assembly-language note: You can tell whether a Macintosh is equipped with 
the 64K ROM version or the hierarchical version of 
the File Manager by examining the contents of the 
global variable FSFCBLen; if the 64K ROM version is 
running, FSFCBLen will contain —1. You can determine 
if a mounted volume is flat or hierarchical by 
calling the HGetVInfo function. 


Working Directories 
eeeClick on the X-Ref button, and refer to Technical Note #190.+e« 


It's useful to look at the relationship between the 64K ROM and 128K ROM 
versions of the File Manager. In the 64K ROM version, the entire volume is a 
single directory (you could consider it a barren root directory). It would seem 
that existing applications, when introduced on a machine equipped with the 128K 
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ROM version of the File Manager, would be unable to handle the specification of 
which directory a file is in, since they only exchange volume reference numbers 
and file names with the Finder and the File Manager. The 128K ROM version, 
however, introduces the notion of a working directory to allow existing 
applications to operate with the hierarchical file system. 


When the File Manager makes a particular directory a working directory (using 
the function OpenwD), it stores the directory ID, as well as the volume 
reference number of the volume on which the directory is located, in a working 
directory control block. The File Manager then returns a unique working 
directory reference number which you can use in subsequent calls to refer to 
that directory. 


Directories can be seen as mini-volumes. (The root directory is, in fact, just 
another mini-volume; it contains only the files and directories immediately 
below it in the tree structure.) A working directory reference number is just 
like a volume reference number for a directory. It's a temporary reference 
number that specifies where a file is located on a hierarchical volume. 


This relationship allows the hierarchical file system to be compatible with 
existing applications. A working directory reference number can be used in place 
of a volume reference number in any File Manager call. When you provide a 
working directory reference number, the File Manager uses it to determine which 
directory a file is in, as well as which volume the directory and file are on. 


An example of the use of working directories is a situation where the Finder 
opens a document. With the 64K ROM version of the File Manager, when the Finder 
launches the application that handles the document, it has only to pass the 
volume reference number and file name of the document. With the 128K ROM 
version, the Finder makes the directory containing the file a working directory, 
and passes the application a working directory reference number instead of the 
volume reference number. Upon being launched, the application opens the file, 
passing the File Manager the working directory reference number received from 
the Finder. 


Warning: The possibility of incompatibility arises for programmers who 
(despite numerous warnings) have written code that accesses and 
manipulates low-level data structures directly (such as volume 
control blocks and file control blocks). Programmers in this 
category will want to study the sections "Data Organization on 
Volumes" and "Data Structures in Memory". 


Pathnames 
eeeClick on the X-Ref button, and refer to Technical Note #238. eee 


The 128K ROM version of the File Manager also permits the specification of files 
(and directories) using concatenations of volume names, directory names, and 
file names. Separated by colons, these concatenations of names are known as 
pathnames. 


A full pathname always begins with the name of the root directory; it names the 
path from the root to a given file or directory, and includes each of the 
directories visited on that path (see Figure 2). For instance, a full pathname 
to the file Geri is: 
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MyDisk:Correspondence:Letters:Family:Geri 


A full pathname is a complete and unambiguous identification of a file or 
directory. You should avoid using full pathnames; they are cumbersome to enter 
and it takes longer to process them. 


Another type of identification is a partial pathname, which describes the path 
to a file or directory starting from a given directory. When using a partial 
pathname, you must also specify the directory from which the partial pathname 
begins; this is discussed below. 


64K ROM note: In the 64K ROM version of the File Manager, the combination 
of volume name followed by the file name constitutes a full 
pathname. A file name alone constitutes a partial pathname; 
the directory from which this partial pathname begins (the 
root directory) is specified by the volume reference number. 


To distinguish them from full pathnames, partial pathnames must begin with a 
colon, except in the case where the partial pathname contains only one name. 
(This exception is needed to maintain compatibility with 64K ROM version of the 
File Manager, where the only partial pathnames—file names—do not begin with a 
colon.) For the file Geri in Figure 2, a valid partial pathname, starting from 
the directory Letters, would be: 


:Family:Geri 


The above pathname begins at the directory Letters and moves down the tree to 
the file Status. It's also possible to move up the tree by using consecutive 
colons (::). This notation indicates, for instance, that the name following a 
double colon is an offspring of the current location's parent, rather than an 
offspring of the directory preceding the double colon. In Figure 2, for example, 
the file Letter Form can be specified by the full pathname 


MyDisk:Correspondence:Letters:Family:::Template 


where the consecutive colons signify a move up the tree from Family to Letters 
and finally to Correspondence. 


If a full pathname consists of only one name (the volume name), the pathname 
must end in a colon. For pathnames to other directories, if the last name is 
followed by a colon, the colon is ignored. Multiname pathnames describing a file 
should not end in a colon. 


To summarize, if the first character of a pathname is a colon, or if the 
pathname contains no colons, it must be a partial pathname; otherwise, it's a 
full pathname. 


Warning: While there's no limit to the number of levels of subdirectories 
allowed, it may not always be possible in the case of a large 
volume to specify every file and directory with a full pathname, 
since character strings are limited to 255 characters. In such 
cases, you can obtain the directory ID of a subdirectory somewhere 
along the path and use it with a partial pathname to specify the 
desired file or directory. 
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Specifying Volumes, Directories, and Files 


A volume can be specified explicitly by its name, its volume reference number, 
or its drive number, and implicitly by a working directory reference number or a 
full pathname. The File Manager searches for volume specifications in the 
following order: 


1. It looks for a volume name. (Remember, it must be followed by a colon. ) 

2. If the name specified is NIL or an improper name, the File Manager looks 
for either a volume reference number, a drive number, or a working 
directory reference number. 


With routines that operate on a volume, such as mounting or ejecting, if you 
don't provide any of these specifications, the File Manager assumes you want to 
perform the operation on the default volume. Initially, the volume used to start 
up the application is set as the default volume, but an application can 
designate any mounted volume as the default volume. 


With routines that access files (or directories), if no directory is specified 
and the volume reference number passed is zero, the File Manager assumes that 
the file or directory is located in the default directory. Initially, the 
default directory is set to the root directory of the volume used to start up 
the application, but an application can designate any directory as the default 
directory. 


To access a file or directory, you need to specify its name, the directory it's 
in, and which volume it's on. There are a number of ways of doing this: 


e Full pathname. A full pathname completely specifies a file or directory. 
Since the first name in a full pathname (the name of the root directory) 
is always the name of the volume, no separate volume specification is 
needed. In fact, a full pathname will override an explicit volume 
specification. (This specification runs the risk of ambiguity since 
there could be two mounted volumes with the same name. ) 

e Volume reference number and partial pathname. This is the most common 
type of specification, since it's the only form of specification in 
the 64K ROM version of the File Manager. The volume reference number 
specifies the volume as well as the directory (the root) to be used 
with the partial pathname (the file name). 

« Directory ID and partial pathname. Another way to specify a file or 
directory is to use the directory ID of any directory in the catalog 
along with a partial pathname from that directory. Since neither the 
directory ID nor the partial pathname indicates the name of the volume, 
a separate volume specification is also needed. 

e Working directory reference number and partial pathname. This is the 
most common type of specification in the 128K ROM version of the File 
Manager. It's similar to the previous one; it does not, however, require 
a separate volume specification. The working directory reference number 
is used to obtain both the directory ID (to be used with the partial 
pathname) and the volume reference number. 


If both a directory ID and a working directory reference number are specified, 
the directory ID is used to identify the directory on the volume indicated by 
the working directory reference number. In other words, a directory ID specified 
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by the caller will override the directory referred to by the working directory 
reference number. 


Advanced programmers: If the File Manager doesn't find a given file in the 
directory specified, it looks in the directory 
containing the currently open System file (obtained 
from the global variable BootDrive or sysVRefNum from 
_SysEnvirons) provided it's on the volume specified by 
the call. If the file isn't found there, the File 
Manager looks in the folder, on the volume specified by 
the call, whose directory ID is returned in the 
vcbFndrinfo field by the HGetVInfo function. 


Warning: It's important to be aware of this search path. You can't assume 
that a given file is located in the directory that you specified 
when accessing it. 


Indexing 
e*eClick on the X-Ref button, and refer to Technical Note #68.+e« 


In most of the File Manager routines, you'll be referring to a particular file, 
directory, or volume by its name or some sort of reference number. With a 
routine such as GetFileInfo, however, you may want to make the same call 
repeatedly for all files in a given directory without specifying each file 
individually. Such routines provide a parameter where you can simply specify an 
index number. In the first iteration of the GetFileInfo function, for example, 
you would pass an index of 1 and get information about the first file in a given 
directory. In the second iteration you would pass an index of 2, and so on. 


It's possible to determine how many files are contained in a given directory and 
thereby specify the number of iterations for a GetFileInfo indexing loop. The 
presence of subdirectories, however, complicates the situation. A faster and 
more reliable technique is to begin with an index of 1 and continue until the 
result code fnfErr (file not found) is returned. 


The routines that allow you to provide an index are: GetVolInfo, GetFileInfo, 
GetCatInfo, GetWDInfo, and GetFCBInfo. Respectively, they provide information 
about mounted volumes, files in a given directory, files and directories ina 
given directory, working directories, and file control blocks. 


On flat volumes, programmers can use the function GetFileInfo to index through 
all the files on a volume. On hierarchical volumes, files can be in 
subdirectories, which may themselves contain other subdirectories and files. 
With such volumes, you should instead use GetCatInfo since it returns 
information about both files and directories. 


Advanced programmers: While it's questionable whether an application would 
want to index through all the files on a hierarchical 
volume (since such a volume may contain a large number 
of files), you may want to index through a particular 
directory or portion of the tree structure. You can use 
GetCatInfo in a recursive way to do this. While indexing 
through the initial directory, if a subdirectory is 
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found, you need to interrupt the indexing of the initial 
directory and index through the subdirectory. 


Accessing Files 


To create a new, empty file, call Create. Create allows you to set some of the 
information stored on the volume about the file. DirCreate allows you to create 
directories. 


To open a file, call Open. The File Manager creates an access path and returns a 
path reference number that you'll use every time you want to refer to it. Before 
you open a file, you may want to call the Standard File Package, which presents 
the standard interface through which the user can specify the file to be opened. 
The Standard File Package will return the name of the file, the volume reference 
number or working directory reference number, and additional information. (If 
the user inserts an unmounted volume into a drive, the Standard File Package 
will automatically call the Disk Initialization Package to attempt to mount it.) 


After opening a file, you can transfer data from it to an application's data 
buffer with Read, and send data from an application's data buffer to the file 
with Write. If you've opened a file with shared read/write permission, you need 
to call LockRng before writing to it in order to prevent another access path 
from writing to the same portion of the file. When you're done writing, call 
UnlockRng to release that portion of the file. 


You can't use Write on a file whose open permission only allows reading, or ona 
file on a locked volume. In addition, you can't write to a range that's been 
locked by another access path with the LockRng call. 


You can specify the byte position of the mark before calling Read or Write by 
calling SetFPos. GetFPos returns the byte position of the mark. 


Once you've completed whatever reading and writing you want to do, call Close to 
close the file. Close writes the contents of the file's access path buffer to 
the volume and deletes the access path. You can remove a closed file (both 
forks) from a volume by calling Delete. 


Applications will normally use the Resource Manager to open resource forks and 
change the information contained within, but programmers writing unusual 
applications (such as a disk-copying utility) might want to use the File Manager 
to open resource forks. This is done by calling OpenRF. As with Open, the File 
Manager creates an access path and returns a path reference number that you'll 
use every time you want to refer to this resource fork. 


Accessing Volumes 


When the Toolbox Event Manager function GetNextEvent receives a disk-inserted 
event, it calls the Desk Manager function SystemEvent. SystemEvent calls the 
File Manager function MountVol, which attempts to mount the volume on the disk. 
GetNextEvent then returns the disk-inserted event: The low-order word of the 
event message contains the number of the drive, and the high-order word contains 
the result code of the attempted mounting. If the result code indicates that an 
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error occurred, you'll need to call the Disk Initialization Package to allow the 
user to initialize or eject the volume. 


Note: Applications that rely on the Operating System Event Manager function 
GetOSEvent to learn about events (and don't call GetNextEvent) must 
explicitly call MountVol to mount volumes. 


After a volume has been mounted, your application can call GetVolInfo, which 
will return the name of the volume, the amount of unused space on the volume, 
and a volume reference number that you can use to refer to that volume. The 
volume reference number is also returned by MountVol. 


To minimize the amount of memory used by mounted volumes, an application can 
unmount or place off-line any volumes that aren't currently being used. To 
unmount a volume, call UnmountVol, which flushes a volume (by calling FlushVol) 
and releases all of the memory used for it. To place a volume off-line, call 
OffLine, which flushes a volume and releases all of the memory used for it 
except for the volume control block. Off-line volumes are placed on-line by the 
File Manager as needed, but your application must remount any unmounted volumes 
it wants to access. The File Manager itself may place volumes off-line during 
its normal operation. 


To protect against power loss or unexpected disk ejection, you should 
periodically call FlushVol (probably after each time you close a file), which 
writes the contents of the volume buffer and all access path buffers (if any) to 
the volume and updates the descriptive information contained on the volume. 


Whenever your application is finished with a disk, or when the user chooses 
Eject from a menu, call Eject. Eject calls FlushVol, places the volume off-line, 
and then physically ejects the volume from its drive. 


If you would like all File Manager calls to apply to one volume, you can specify 
that volume as the default. You can use SetVol to set the default volume to any 
mounted volume, and GetVol to learn the name and volume reference number of the 
default volume. 


The preceding paragraphs covered the basic File Manager routines. The remainder 
of this section describes some less commonly used routines. 


Advanced Routines 


Normally, volume initialization and naming is handled by the Standard File 
Package, which calls the Disk Initialization Package. If you want to initialize 
a volume explicitly or erase all files from a volume, you can call the Disk 
Initialization Package directly. When you want to change the name of a volume, 
call the File Manager function Rename. 


Whenever a disk has been reconstructed in an attempt to salvage lost files 
(because its directory or other file-access information has been destroyed), the 
logical end-of-file of each file will probably be equal to its physical 
end-of-file, regardless of where the actual logical end-of-file is. The first 
time an application attempts to read from a file on a reconstructed volume, it 
will blindly pass the correct logical end-of-file and read misinformation until 
it reaches the new, incorrect logical end-of-file. To prevent this from 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
THE FILE MANAGER e 32 of 150 


happening, an application should always maintain an independent record of the 
logical end-of-file of each file it uses. To determine the File Manager's 
conception of the size of a file, or to find out how many bytes have yet to be 
read from it, call GetEOF, which returns the logical end-of-file. You can change 
the length of a file by calling SetEOF. 


Allocation blocks are automatically added to and deleted from a file as 
necessary. If this happens to a number of files alternately, each of the files 
will be contained in allocation blocks scattered throughout the volume, which 
increases the time required to access those files. To prevent such fragmentation 
of files, you can allocate a number of contiguous allocation blocks to an open 
file by calling Allocate or AllocContig. 


Instead of calling FlushVol, an unusual application might call FlushFile. 
FlushFile forces the contents of a file's volume buffer and access path buffer 
(if any) to be written to its volume. FlushFile doesn't update the descriptive 
information contained on the volume, so the volume information won't be correct 
until you call FlushVol. 


To get information about a file in a given directory (such as its name and 
creation date), call GetFileInfo; you can change this information by calling 
SetFileInfo. On hierarchical volumes, you can get information about both files 
and directories by calling GetCatInfo; you can change this information with 
SetCatInfo. Changing the name of a file is accomplished by calling Rename. You 
can lock a file by calling SetFilLock; to unlock a file, call RstFilLock. Given 
a path reference number, you can get the volume reference number of the volume 
containing that file by calling either GetVRefNum or GetFCBInfo (described in 
the section "Data Structures in Memory"). 


64K ROM note: You can change the version number of a file by calling 
SetFilType. 


To make a particular directory a working directory, call OpenWD; you can remove 
a working directory with CloseWD. To get information about a working directory 
(from its working directory control block), call GetWDInfo. 


THE SHARED ENVIRONMENT CALLS 


This section describes the interface to the new calls used in supporting shared 
environments. Though the calls are not necessarily specific to AppleShare, the 
example descriptions keep the implementation of AppleShare in mind. 


For AppleShare startup volumes, these calls get installed by an 'INIT' resource 
patch contained within the AppleShare file. This means that only startup 
volumes with the AppleShare file located in its System Folder will support the 
shared environment calls. Since the patch currently handles only external file 
system volumes, making the new calls to local volumes will return with an 
error; however, the AppleShare external file system code will get all calls made 
to AppleShare volumes. 


Assembly-language note: You can invoke each of these routines with a macro, 
whose name is presented with the call description. 
The macros expand to HFSDispatch ($A260) calls with 
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an index value passed in register DQ. The routine 
selectors are as follows: 


Macro Name Call number 
_GetCatInfo $09 
_GetVolParms $30 


_GetLogInInfo $31 
_GetDirAccess $32 
_SetDirAccess $33 


_MapID $34 
_MapName $35 
_CopyFile $36 
_MoveRename $37 
_OpenDeny $38 
_OpenRFDeny $39 


HFS Support 


The simplest way to determine if your HFS supports these new calls is to make 
the PBHGetVolParms call to a mounted volume. If a paramErr error is returned 
and you have set the correct parameters, then the volume does not support these 
new calls. 


Making successive PBHGetVolParms calls to each mounted volume is a good way to 
tell if any of the volumes support these calls. Once you find a volume that 
returns noErr to the call, examine the information to see if that volume 
Supports various functions (such as access privileges and PBHCopyFile) that you 
may need. 


Error Reporting 


Most error codes returned by these calls map directly into existing Macintosh 
error equates, but some cannot, and new error equates have been defined for 
them: 


VolGoneErr —124 Connection to the server volume has been 
disconnected, but the VCB is still around 
and marked offline. 


AccessDenied —5000 The operation has failed because the user does 
not have the correct access to the file/folder. 
DenyConflict —5006 The operation has failed because the permission 


or deny mode conflicts with the mode in which 
the fork has already been opened. 


NoMoreLocks —5015 Byte range locking has failed because the server 
cannot lock any additional ranges. 

RangeNotLocked —5020 User attempted to unlock a range that was not 
locked by this user. 

RangeOverlap —5021 User attempted to lock some or all of a range 


that is already locked. 


The AppleTalk AFP protocol returns errors in the range of —5000 to —5030. Since 
it is possible, though unlikely, to receive error codes in this range, it would 
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be wise to handle these undocumented error codes in a generic fashion. If you 
require it, the complete list of these error codes can be found in the AppleTalk 
AFP Protocol specification document or Inside AppleTalk. 


Data Structures 


Some of the new data structures used by these calls are described below. 
Specific information about the placement and setting of parameters is described 
with the call. 


For PBHGetLogInInfo, ioObjType contains the log in method, where the following 
values are recognized: 


1 guest user 

2 registered user—clear text password 
3 registered user—scrambled password 
4-127 reserved by Apple for future use 


128-255 user-defined values 


For PBHMapName and PBHMapID, ioObjType contains a mapping code. The PBHMapID 
call recognizes these codes: 


1 map owner ID to owner name 
2 map group ID to group name 


and MapName recognizes these codes: 


3 map owner name to owner ID 
4 map group name to group ID 


For PBHGetDirAccess and PBHSetDirAccess, ioACAccess is a long integer that 
contains access rights information in the format uueeggoo, where uu = user's 
rights, ee = everyone's rights, gg = group's rights, and 00 = owner's rights. 


Note: In AppleShare 1.0 and 1.1, the Write bit represents Make Changes 
privileges, the Read bit represents See Files privileges, and the 
Search bit represents See Folders privileges. 


Unused bits should always be cleared. A pictorial representation is shown in 
Figure 9 (high-order bit on the left). 
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i directory owner 


User's rights 
Everyone's rights 
Group's rehts 
Crvmer's rights 


Read 
Beach, 


Figure 9-Access Rights in loAC Access 


Figure 9-Access Rights in IoACAccess 


Bit 7 If set, user is not the owner of the directory. 
If clear, user is the owner of the directory. 
6-3 Reserved; this is returned set to zero. 


2 If set, user does not have Write privileges to the directory. 
If clear, user has Write privileges to the directory. 

1 If set, user does not have Read privileges to the directory. 
If clear, user has Read privileges to the directory. 

0 If set, user does not have Search privileges to the directory. 


If clear, user has Search privileges to the directory. 


The User's rights information is the logical OR of Everyone's rights, Group's 
rights, and Owner's rights. It is only returned from the GetDirAccess call; it 
is never passed by the SetDirAccess call. Likewise, the Owner bit is only 
returned in the GetDirAccess call. To change a folder's owner, you must change 
the Owner ID field of the SetDirAccess call. 


For PBHOpenDeny and PBHOpenRFDeny, ioDenyModes contain a word of permissions 
information, as pictured in Figure 10 (high order bit on the left). 


jo Jo jo fo fo fo fo fo fo jofxpxfojofxx 


deny other wiiters —f | 
deny other readers 
Teq west write permission 


request read permission 


Figure 10—Pemmission Bits 
Figure 10—Permission Bits 


Bit 15-6 Reserved; this should be set to zero. 
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If set, deny other writers to this file. 
If set, deny other readers to this file. 
Reserved; this should be set to zero. 

If set, requesting write permission. 

If set, requesting read permission. 


Sen 
N 


For PBGetCatInfo, ioACUser (a new byte field) returns the user's access rights 
information for a directory whose volume supports access controls in the format 


shown in Figure 11. 
fx}o fo fo fo px px x 


directory owner =} 
Write privileges 
read privileves 


search privileges 


Figure 11-—Access Richt to wACUser 
Figure 11—Access Rights in ioACUser 
Bit 7 If set, user is not the owner of the directory. 


If clear, user is the owner of the directory. 
6-3 Reserved; this is returned set to zero. 


2 If set, user does not have Write privileges to the directory. 
If clear, user has Write privileges to the directory. 

1 If set, user does not have Read privileges to the directory. 
If clear, user has Read privileges to the directory. 

0 If set, user does not have Search privileges to the directory. 


If clear, user has Search privileges to the directory. 
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INFORMATION USED BY THE FINDER 


The file directory (whether hierarchical or flat) lists information about all 
the files and directories on a volume. This information is returned by the 
GetFileInfo and GetCatInfo functions. 


Flat Volumes 

eeeClick on the X-Ref button, and refer to Technical Note #40. eee 

On flat volumes, all of the information used by the Finder is contained in a 
data structure of type FInfo. (This data structure is also used with 
hierarchical volumes, along with additional structures described below.) The 
FInfo data type is defined as follows: 


TYPE FInfo = RECORD 


fdType: OSType; {file type} 

fdCreator: OSType; {file's creator} 

fdFlags: INTEGER; {flags} 

fdLocation: Point; {file's location} 

fdFldr: INTEGER {file's window} 
END; 


Normally an application need only set the file type and creator when a file is 
created, and the Finder will manipulate the other fields. (File type and creator 
are discussed in the Finder Interface chapter. ) 


FdFlags indicates whether the file's icon is invisible, whether the file has a 
bundle, and other characteristics used internally by the Finder: 


Bit Meaning 

0 Set if file is on desktop (hierarchical volumes only) 
13 Set if file has a bundle 

14 Set if file's icon is invisible 


Masks for these three bits are available as predefined constants: 


CONST fOnDesk 


1; {set if file is on desktop (hierarchical } 
{ volumes only)} 

8192; {set if file has a bundle} 

16384; {set if file's icon is invisible} 


fHasBundle 
fInvisible 


For more information about bundles, see the Finder Interface chapter. 


FdLocation contains the location of the file's icon in its window, given in the 
local coordinate system of the window; it's used by the Finder to position the 
icon. FdFldr indicates the window in which the file's icon will appear, and may 
contain one of the following values: 
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CONST fTrash = -3; {file is in Trash window} 
fDesktop = -2; {file is on desktop} 
fDisk = 0; {file is in disk window} 


64K ROM note: The fdFldr field of FInfo is not used with hierarchical volumes. 


Hierarchical Volumes 


On hierarchical volumes, in addition to the FInfo record, the following 
information about files is maintained for the Finder: 


TYPE FXInfo = RECORD 


fdIconID: INTEGER; {icon ID} 

fdUnused: ARRAY[1..4] OF INTEGER; {reserved} 

fdComment: INTEGER; {comment ID} 

fdPutAway: LONGINT; {home directory ID} 
END; 


On hierarchical volumes, the following information about directories is 
maintained for the Finder: 


DInfo = RECORD 


frRect: Rect; {folder's rectangle} 
frFlags: INTEGER; {flags} 
frLocation: Point; {folder's location} 
frView: INTEGER; {folder's view} 

END; 

DXInfo = RECORD 

frScroll: Point; {scroll position} 
frOpenChain: LONGINT; {directory ID chain of open folders} 
frUnused: INTEGER; {reserved} 
frComment: INTEGER; {comment ID} 
frPutAway: LONGINT; {directory ID} 

END; 


When a file (or folder) is moved to the desktop on a hierarchical volume, it's 
actually moved to the root level of the file directory. (This permits all the 
desktop icons to be enumerated by one simple scan of the root.) The fOnDesk bit 
of fdFlags is set. FDPutAway (or frPutAway for directories) contains the 
directory ID of the folder that originally contained the file (or folder); this 
allows the file (or folder) to be returned there from the desktop. 
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HIGH-LEVEL FILE MANAGER ROUTINES 


eeeClick on the X-Ref button, and refer to Technical Note #218.¢ee 


This section describes all the high-level Pascal routines of the File Manager. 
For information on calling the low-level Pascal and assembly-language routines, 
see the next section. 


When accessing a volume other than the default volume, you must identify it by 
its volume name, its volume reference number, the drive number of its drive, or 
a working directory reference number. The parameter volName is a pointer, of 
type StringPtr, to the volume name. DrvNum is an integer that contains the drive 
number, and vRefNum is an integer that can contain either the volume reference 
number or a working directory reference number. 


Note: VolName is declared as type StringPtr instead of type STRING to allow 
you to pass NIL in routines where the parameter is optional. 


Warning: Before you pass a parameter of type StringPtr to a File Manager 
routine, be sure that memory has been allocated for the variable. 
For example, the following statements will ensure that memory is 
allocated for the variable myStr: 


VAR myStr: Str255; 
result := GetVol (@myStr,myRefNum) 


FileName can contain either the file name alone or both the volume name and file 
name. 


Note: The high-level File Manager routines will work only with files 
having a version number of 0. 


You can't specify an access path buffer when calling high-level Pascal routines. 


ALL high-level File Manager routines return an integer result code of type OSErr 
as their function result. Each routine description lists all of the applicable 
result codes, along with a short description of what the result code means. 
Lengthier explanations of all the resultcodes can be found in the summary at the 
end of this chapter. 


Accessing Volumes 
eeeClick on the X-Ref button, and refer to Technical Note #24. +ee« 


FUNCTION GetVInfo (drvNum: INTEGER; volName: StringPtr; VAR vRefNum: INTEGER; 
VAR freeBytes: LONGINT) : OSErr; [Not in ROM] 


e*eClick on the X-Ref button, and refer to Technical Note #157.¢ee 
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GetVInfo returns the name, reference number, and available space (in bytes), in 
volName, vRefNum, and freeBytes, for the volume in the drive specified by 
drvNum. 


Result codes noErr No error 
nsvErr No default volume 
paramErr Bad drive number 


FUNCTION GetVRefNum (pathRefNum: INTEGER; VAR vRefNum: INTEGER) : OSErr; 
[Not in ROM] 


Given a path reference number in pathRefNum, GetVRefNum returns the volume 
reference number in vRefNum. 


Result codes noErr No error 
rfNumErr Bad reference number 


FUNCTION GetVol (volName: StringPtr; VAR vRefNum: INTEGER) : OSErr; 
[Not in ROM] 


GetVol returns the name of the default volume in volName and its volume 
reference number in vRefNum. 


Result codes noErr No error 
nsvErr No such volume 


FUNCTION SetVol (volName: StringPtr; vRefNum: INTEGER) : OSErr; [Not in ROM] 


SetVol sets the default volume to the mounted volume specified by volName or 
vRefNum. 


Result codes noErr No error 
bdNamErr Bad volume name 
nsvErr No such volume 
paramErr No default volume 


FUNCTION FlushVol (volName: StringPtr; vRefNum: INTEGER) : OSErr; 
[Not in ROM] 


On the volume specified by volName or vRefNum, FlushVol writes the contents of 
the associated volume buffer and descriptive information about the volume (if 
they've changed since the last time FlushVol was called). 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 
ioErr I/O error 
nsDrvErr No such drive 
nsvErr No such volume 
paramErr No default volume 


FUNCTION UnmountVol (volName: StringPtr; vRefNum: INTEGER) : OSErr; 
[Not in ROM] 
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UnmountVol unmounts the volume specified by volName or vRefNum, by calling 
FlushVol to flush the volume buffer, closing all open files on the volume, and 
releasing the memory used for the volume. 


Warning: Don't unmount the startup volume. 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 
ioErr I/O error 
nsDrvErr No such drive 
nsvErr No such volume 
paramErr No default volume 


FUNCTION Eject (volName: StringPtr; vRefNum: INTEGER) : OSErr; [Not in ROM] 


Eject flushes the volume specified by volName or vRefNum, places it off-line, 
and then ejects the volume. 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 
ioErr I/O error 
nsDrvErr No such drive 
nsvErr No such volume 
paramErr No default volume 


Accessing Files 


FUNCTION FSOpen (fileName: Str255; vRefNum: INTEGER; 
VAR refNum: INTEGER) : OSErr; [Not in ROM] 


FSOpen creates an access path to the file having the name fileName on the volume 
specified by vRefNum. A path reference number is returned in refNum. The access 
path's read/write permission is set to whatever the file's open permission 
allows. 


Note: There's no guarantee that any bytes have been written until 
FlushVol is called. 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
opWrErr File already open for writing 
tmfoErr Too many files open 


FUNCTION OpenRF (fileName: Str255; vRefNum: INTEGER; 
VAR refNum: INTEGER) : OSErr; [Not in ROM] 


OpenRF is similar to FSOpen; the only difference is that OpenRF opens the 
resource fork of the specified file rather than the data fork. A path reference 
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number is returned in refNum. The access path's read/write permission is set to 
whatever the file's open permission allows. 


Note: Normally you should access a file's resource fork through the 
routines of the Resource Manager rather than the File Manager. 
OpenRF doesn't read the resource map into memory; it's really 
only useful for block-level operations such as copying files. 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
opWrErr File already open for writing 
tmfoErr Too many files open 


FUNCTION FSRead (refNum: INTEGER; VAR count: LONGINT; 
buffPtr: Ptr) : OSErr; [Not in ROM] 


FSRead attempts to read the number of bytes specified by the count parameter 
from the open file whose access path is specified by refNum, and transfer them 
to the data buffer pointed to by buffPtr. The read operation begins at the 
current mark, so you might want to precede this with a call to SetFPos. If you 
try to read past the logical end-of-file, FSRead moves the mark to the end-of- 
file and returns eofErr as its function result. After the read is completed, the 
number of bytes actually read is returned in the count parameter. 


Result codes noErr No error 
eofErr End-of-file 
extFSErr External file system 
fnOpnErr File not open 
ioErr I/O error 
paramErr Negative count 
rfNumErr Bad reference number 


FUNCTION FSWrite (refNum: INTEGER; VAR count: LONGINT; 
buffPtr: Ptr) : OSErr; [Not in ROM] 


FSWrite takes the number of bytes specified by the count parameter from the 
buffer pointed to by buffPtr and attempts to write them to the open file whose 
access path is specified by refNum. The write operation begins at the current 
mark, so you might want to precede this with a call to SetFPos. After the write 
is completed, the number of bytes actually written is returned in the count 
parameter. 


Result codes noErr No error 
dskFulErr Disk full 
fLckdErr File locked 
fnOpnErr File not open 
ioErr I/O error 
paramErr Negative count 
rfNumErr Bad reference number 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
wrPermErr Read/write permission doesn't allow writing 
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FUNCTION GetFPos (refNum: INTEGER; VAR filePos: LONGINT) : OSErr; 
[Not in ROM] 


GetFPos returns, in filePos, the mark of the open file whose access path is 
specified by refNum. 


Result codes noErr No error 
extFSErr External file system 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 


FUNCTION SetFPos (refNum: INTEGER; posMode: INTEGER; 
posOff: LONGINT) : OSErr; [Not in ROM] 


SetFPos sets the mark of the open file whose access path is specified by refNum 
to the position specified by posMode and posOff (except when posMode is equal to 
fsAtMark, in which case posOff is ignored). PosMode indicates how to position 
the mark; it must contain one of the following values: 


CONST fsAtMark = 0; fat current mark} 
fsFromStart = 1; {set mark relative to beginning of file} 
fsFromLEOF = 2" {set mark relative to logical end-of- file} 
fsFromMark = 3: {set mark relative to current mark} 


If you specify fsAtMark, posOffset is ignored and the mark is left wherever 

it's currently positioned. If you choose to set the mark (relative to either the 
beginning of the file, the logical end-of-file, or the current mark), posOffset 
specifies the byte offset from the chosen point (either positive or negative) 
where the mark should be set. If you try to set the mark past the logical end- 
of-file, SetFPos moves the mark to the end-of-file and returns eofErr as its 
function result. 


Result codes noErr No error 
eofErr End-of-file 
extFSErr External file system 
fnOpnErr File not open 
ioErr I/O error 
posErr Attempt to position before start of file 
rfNumErr Bad reference number 


FUNCTION GetEOF (refNum: INTEGER; VAR logEOF: LONGINT) : OSErr; [Not in ROM] 


GetEOF returns, in logEOF, the logical end-of-file of the open file whose access 
path is specified by refNum. 


Result codes noErr No error 
extFSErr External file system 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 


FUNCTION SetEOF (refNum: INTEGER; LogEOF: LONGINT) : OSErr; [Not in ROM] 
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SetEOF sets the logical end-of-file of the open file whose access path is 
specified by refNum to the position specified by logEOF. If you attempt to set 
the logical end-of-file beyond the physical end-of-file, the physical end-of- 
file is set to one byte beyond the end of the next free allocation block; if 
there isn't enough space on the volume, no change is made, and SetEOF returns 
dskFulErr as its function result. If logEOF is 0, all space occupied by the file 


on the volume is released. 


Result codes noErr No error 
dskFulErr Disk full 
extFSErr External file system 
flLckdErr File locked 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
wrPermErr Read/write permission doesn't allow writing 


FUNCTION Allocate (refNum: 


INTEGER; VAR count: 


LONGINT) OSErr; [Not in ROM] 


Allocate adds the number of bytes specified by the count parameter to the open 
file whose access path is specified by refNum, and sets the physical end-of-file 
to one byte beyond the last block allocated. The number of bytes actually 
allocated is rounded up to the nearest multiple of the allocation block size, 
and returned in the count parameter. If there isn't enough empty space on the 
volume to satisfy the allocation request, Allocate allocates the rest of the 
Space on the volume and returns dskFulErr as its function result. 


Result codes noErr No error 
dskFulErr Disk full 
fLckdErr File locked 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
wrPermErr Read/write permission doesn't allow writing 


FUNCTION FSClose (refNum: 


INTEGER) 


OSErr; [Not in ROM] 


FSClose removes the access path specified by refNum, writes the contents of the 
volume buffer to the volume, and updates the file's entry in the file directory. 


Note: There's no guarantee that any bytes have been written until 
FlushVol is called. 
Result codes noErr No error 
extFSErr External file system 
fnfErr File not found 
fnOpnErr File not open 
ioErr I/O error 
nsvErr No such volume 
rfNumErr Bad reference number 
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Creating and Deleting Files 


FUNCTION Create (fileName: Str255; vRefNum: INTEGER; creator: OSType; 
fileType: OSType) : OSErr; [Not in ROM] 


Create creates a new file (both forks) with the specified name, file type, and 
creator on the specified volume. (File type and creator are discussed in the 
Finder Interface chapter.) The new file is unlocked and empty. The date and time 
of its creation and last modification are set to the current date and time. 


Result codes noErr No error 
bdNamErr Bad file name 
dupFNErr Duplicate file name and version 
dirFuleErr File directory full 
extFSErr External file system 
ioErr I/O error 
nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION FSDelete (fileName: Str255; vRefNum: INTEGER) : OSErr; [Not in ROM] 


FSDelete removes the closed file having the name fileName from the specified 
volume. 


Note: This function will delete both forks of a file. 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
fBsyErr File busy 
flckdErr File locked 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


Changing Information About Files 


All of the routines described in this section affect both forks of the file, and 
don't require the file to be open. 


FUNCTION GetFinfo (fileName: Str255; vRefNum: INTEGER; 
VAR fndrinfo: FiInfo) : OSErr; [Not in ROM] 


For the file having the name fileName on the specified volume, GetFInfo returns 
information used by the Finder in fndrInfo (see the section "Information Used by 
the Finder"). 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
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fnfErr File not found 


ioErr I/O error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION SetFinfo (fileName: Str255; vRefNum: INTEGER; 
fndrinfo: FiInfo) : OSErr; [Not in ROM] 


For the file having the name fileName on the specified volume, SetFInfo sets 
information used by the Finder to fndriInfo (see the section "Information Used by 
the Finder"). 


Result codes noErr No error 
extFSErr External file system 
flckdErr File locked 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
FUNCTION SetFLock (fileName: Str255; vRefNum: INTEGER) : OSErr; [Not in ROM] 


SetFLock locks the file having the name fileName on the specified volume. Access 
paths currently in use aren't affected. 


Result codes noErr No error 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION RstFLock (fileName: Str255; vRefNum: INTEGER) : OSErr; [Not in ROM] 


RstFLock unlocks the file having the name fileName on the specified volume. 
Access paths currently in use aren't affected. 


Result codes noErr No error 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION Rename (oldName: Str255; vRefNum: INTEGER; 
newName: Str255) : OSErr; [Not in ROM] 


Given a file name in oldName, Rename changes the name of the file to newName. 
Access paths currently in use aren't affected. Given a volume name in oldName or 
a volume reference number in vRefNum, Rename changes the name of the specified 
volume to newName. 


Warning: If you're renaming a volume, be sure that both names end with a colon. 
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Result codes 


noErr 
bdNamErr 
dirFulerr 
dupFNErr 
extFSErr 
flckdErr 
fnfErr 
fsRnErr 
ioErr 
nsvErr 
paramErr 
vLckdErr 
wPrErr 


No error 

Bad file name 
Directory full 
Duplicate file name 
External file system 
File locked 

File not found 
Problem during rename 
I/O error 

No such volume 

No default volume 
Software volume lock 
Hardware volume lock 


THE 
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LOW-LEVEL FILE MANAGER ROUTINES 


This section contains information for programmers using the low-level Pascal or 
assembly- language routines of the File Manager, and describes them in detail. 


Most low-level File Manager routines can be executed either synchronously 
(meaning that the application can't continue until the routine is completed) or 
asynchronously (meaning that the application is free to perform other tasks 
while the routine is executing). Some, however, can only be executed 
synchronously because they use the Memory Manager to allocate and release 
memory. 


When an application calls a File Manager routine asynchronously, an I/O request 
is placed in the file I/O queue, and control returns to the calling 
program—possibly even before the actual I/0 is completed. Requests are taken 
from the queue one at a time, and processed; meanwhile, the calling program is 
free to work on other things. 


The calling program may specify a completion routine to be executed at the end 
of an asynchronous operation. 


At any time, you can clear all queued File Manager calls except the current one 
by using the InitQueue procedure. InitQueue is especially useful when an error 
occurs and you no longer want queued calls to be executed. 


Parameter Blocks 


Routine parameters passed by an application to the File Manager and returned by 
the File Manager to an application are contained in a parameter block, which is 
a data structure in the heap or stack. When there are a number of parameters to 
be passed to, or returned from, a routine, the parameters are grouped together 
in a block and a pointer to the block is passed instead. 


Most low-level calls to the File Manager are of the form 
FUNCTION PBCallName (paramBlock: PtrToParamBlk; async: BOOLEAN) : OSErr; 


PBCallName is the name of the routine. ParamBlock points to the parameter block 
containing the parameters for the routine; its data type depends on the type of 
parameter block. If async is TRUE, the call is executed asynchronously; 
otherwise the call is executed synchronously. The routine returns an integer 
result code of type OSErr. Each routine description lists all of the applicable 
result codes, along with a short description of what the result code means. 
Lengthier explanations of all the result codes can be found in the summary at 
the end of this chapter. 


Assembly-language note: When you call a File Manager routine, AQ must point 
to a parameter block containing the parameters for 
the routine. If you want the routine to be executed 
asynchronously, set bit 10 of the routine trap word. 
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You can do this by supplying the word ASYNC as the 
second argument to the routine macro. For example: 


_Read ,ASYNC 


You can set or test bit 10 of a trap word by using 
the global constant asyncTrpBit. (This syntax applies 
to the Lisa Workshop Assembler; programmers using 
another development system should consult its 
documentation for the proper syntax.) 


ALL File Manager routines except InitQueue return a 
result code in DO. 


There are many parameters used in the File Manager routines. To group them all 
together in a single parameter block would be unmanageable, so several different 
parameter block records have been defined. A summary of these parameter blocks 
is listed in the "Summary of the File Manager Section." 


ParamBlockRec is the record used by all routines in the 64K ROM version of the 
File Manager; these routines include general I/O operations, as well as access 
to information about files and volumes. The RAM-based version of the File 
Manager provides additional calls that are slight extensions of certain basic 
routines, allowing you to take advantage of the hierarchical file directory. For 
instance, HOpen is an extension of the Open call that lets you use a directory 
ID and a pathname to specify the file to be opened. These hierarchical routines 
use the record HParamBlockRec, which is a superset of ParamBlockRec. 


Assembly-language note: The hierarchical extensions of certain basic File 
Manager routines are actually not new calls. For 
instance, Open and HOpen both trap to the same 
routine. The trap word generated by the HOpen macro 
is the same as the trap word that would be generated 
by invoking the Open macro with bit 9 set. (Note that 
this is the same bit used in the Device Manager to 
indicate that a particular call should be executed 
immediately.) The setting of this bit tells the File 
Manager to expect a larger parameter block containing 
the additional fields (such as a directory ID) needed 
to handle a hierarchical directory volume. You can set 
or test bit 9 of a trap word by using the global 
constant hfsBit. 


Three parameter block records—CInfoPBRec, CMovePBRec, and WDPBRec—are used by 
routines that deal specifically with the hierarchical file directory. These 
routines work only with the 128K ROM version of the File Manager. 


Finally, the record FCBPBRec is used by a single routine, PBGetFCBInfo, to gain 
access to the contents of a file's file control block; this routine also works 
only with the 128K ROM version of the File Manager. 


Assembly-language note: You can invoke each of the routines that deal 
specifically with the hierarchical file directory 
with a macro that has the same name as the routine 
preceded by an underscore. These macros, however, 
aren't trap macros themselves; instead they expand 
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to invoke the trap macro _HFSDispatch. The File 
Manager determines which routine to execute from 
the routine selector, an integer that's placed in 
register DO. The routine selectors are as follows: 


Routine Call number 


OpenwWD 1 
ClosewD 2 
CatMove 5 
DirCreate 6 
GetwDInfo 7 
GetFCBInfo 8 
GetCatiInfo 9 
SetCatInfo 10 
SetVolInfo 11 
LockRng 16 
UnlockRng 17 


Warning: Using these routines on a Macintosh equipped only with the 

64K ROM will result in a system error. 
Three of the records—ParamBlockRec, HParamBlockRec, and CInfoPBRec—have CASE 
statements that separate some of their parameters into functional subsections 
(also known as variants of the record). The other records—CMovePBRec, WDPBRec, 
and FCBPBRec—are not divided in this way. 


All of the parameter block records used by the File Manager begin with eight 
fields of standard information: 


qLink: QElemPtr; {next queue entry} 

qType: INTEGER; {queue type} 

ioTrap: INTEGER; {routine trap} 

ioCmdAddr: Ptr; {routine address} 

ioCompletion: ProcPtr; {completion routine} 

ioResult: OSErr; {result code} 

ioNamePtr: StringPtr; {pathname} 

ioVRefNum: INTEGER; {volume reference number, drive number, or working } 


{ directory reference number} 


The first four fields in each parameter block are handled entirely by the File 
Manager, and most programmers needn't be concerned with them; programmers who 
are interested in them should see the section "Data Structures in Memory". 


IOCompletion contains a pointer to a completion routine to be executed at the 
end of an asynchronous call; it should be NIL for asynchronous calls with no 
completion routine, and is automatically set to NIL for all synchronous calls. 


eeeClick on the X-Ref button, and refer to Technical Note #130. ¢ee 


Warning: Completion routines are executed at the interrupt level and must 
preserve all registers other than AO, Al, and DQ-D2. Your completion 
routine must not make any calls to the Memory Manager, directly or 
indirectly, and can't depend on handles to unlocked blocks being 
valid. If it uses application globals, it must also ensure that 
register A5 contains the address of the boundary between the 
application globals and the application parameters; for details, 
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see SetUpA5 and RestoreA5 in the Operating System Utilities chapter. 


When your completion routine is called, register AO points to the parameter 
block of the asynchronous call and register DO contains the result code. 


Routines that are executed asynchronously return control to the calling program 
with the result code noErr as soon as the call is placed in the file I/O queue. 
This isn't an indication of successful call completion, but simply indicates 
that the call was successfully queued. 


To determine when the call is actually completed, you can poll the ioResult 
field; this field is set to 1 when the call is made, and receives the actual 
result code upon completion of the call. Completion routines are executed after 
the result code is placed in ioResult. 


IONamePtr points to a pathname (i.e. it does not itself contain the characters. 
It can be either a full or partial pathname. In other words, it can be a volume 
name (that is, the name of the root directory), a file name, or a concatenation 
of directory and file names. If ioNamePtr is NIL or points to an improper 
pathname, an error is returned. For routines that access directories, if a 
directory ID is specified, ioNamePtr can be NIL. 


eeeClick on the X-Ref button, and refer to Technical Note #179, eee 


Note: Although ioNamePtr can be a full pathname, you should not require 
users to enter full pathnames. 


IOVRefNum contains either a volume reference number, a drive number, or a 
working directory reference number. 


The remainder of the parameters are presented below, organized by parameter 
block records. 


I0Param Variant (ParamBlockRec and HParamBlockRec) 


The ioParam variants of ParamBlockRec and HParamBlockRec are identical; the 
fields are presented below. 


ioParam: 
(ioRefNum: INTEGER; {path reference number} 
ioVersNum: SignedByte; {version number} 
ioPermssn: SignedByte; {read/write permission} 
ioMisc: Ptr; {miscellaneous} 
ioBuffer: Ptr; {data buffer} 
ioReqCount: LONGINT; {requested number of bytes} 
ioActCount: LONGINT; factual number of bytes} 
ioPosMode: INTEGER; {positioning mode and newline character} 
ioPosOffset: LONGINT); {positioning offset} 


For routines that access open files, the File Manager determines which file to 
access by using the path reference number in ioRefNum. 


64K ROM note: The 64K ROM version of the File Manager also allows the 
specification of a version number to distinguish between 
different files with the same name. Version numbers are 
generally set to 0, though, because the Resource Manager, 
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Segment Loader, and Standard File Package won't operate 
on files with nonzero version numbers, and the Finder 
ignores version numbers. 


IOPermssn requests permission to read or write via an access path, and must 
contain one of the following values: 


CONST fsCurPerm = Q; {whatever is currently allowed} 
fsRdPerm = 1; {request for read permission only} 
fswrPerm = 2 {request for write permission} 
fsRdWrPerm =13 {request for exclusive read/write permission} 
fsRdWrShPerm = 4; {request for shared read/write permission} 


This request is compared with the open permission of the file. If the open 
permission doesn't allow I/0 as requested, a result code indicating the error is 
returned. 


Warning: To ensure data integrity be sure to lock the portion of the 
file you'll be using if you specify shared write permission. 


The content of ioMisc depends on the routine called. It contains either a new 
logical end-of-file, a new version number, a pointer to an access path buffer, 
or a pointer to a new pathname. Since ioMisc is of type Ptr, you'll need to 
perform type coercion to correctly interpret the value of ioMisc when it 
contains an end-of-file (a LONGINT) or version number (a SignedByte) . 


I0Buffer points to a data buffer into which data is written by Read calls and 
from which data is read by Write calls. I0ReqCount specifies the requested 
number of bytes to be read, written, or allocated. I0ActCount contains the 
number of bytes actually read, written, or allocated. 


IOPosMode and ioPosOffset specify the position of the mark for Read, Write, 
LockRng, UnlockRng, and SetFPos calls. I0PosMode contains the positioning mode; 
bits 0 and 1 indicate how to position the mark, and you can use the following 
predefined constants to set or test their value: 


CONST fsAtMark = 0; {at current mark} 
fsFromStart = 1; {set mark relative to beginning of file} 
fsFromLEOF = 2; {set mark relative to logical end-of-file} 
fsFromMark = 3; {set mark relative to current mark} 


If you specify fsAtMark, ioPosOffset is ignored and the operation begins 
wherever the mark is currently positioned. If you choose to set the mark 
(relative to either the beginning of the file, the logical end-of-file, or the 
current mark), ioPosOffset must specify the byte offset from the chosen point 
(either positive or negative) where the operation should begin. 


Note: Advanced programmers: Bit 7 of ioPosMode is the newline flag; it's 
set if read operations should terminate at a newline character. The 
ASCII code of the newline character is specified in the high-order 
byte of ioPosMode. If the newline flag is set, the data will be read 
one byte at a time until the newline character is encountered, 
ioReqCount bytes have been read, or the end-of-file is reached. If 
the newline flag is clear, the data will be read one byte at a time 
until ioReqCount bytes have been read or the end-of-file is reached. 
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To have the File Manager verify that all data written to a volume exactly 
matches the data in memory, make a Read call right after the Write call. The 
parameters for a read-verify operation are the same as for a standard Read call, 
except that the following constant must be added to the positioning mode: 


CONST rdVerify = 64; {read-verify mode} 

The result code ioErr is returned if any of the data doesn't match. 

FileParam Variant ( ParamBlockRec and HParamBlockRec) 

The fileParam variants of ParamBlockRec and HParamBlockRec are identical, with 
one exception: The field ioDirID in HParamBlockRec is called ioFlNum in 
ParamBlockRec. The fields of the fileParam variant of HParamBlockRec are as 
follows: 


eeeClick on the X-Ref button, and refer to Technical Note #204, eee 


fileParam: 
(ioFRefNum: INTEGER; {path reference number} 
ioFVersNum: SignedByte; {version number} 
fillerl: SignedByte; {not used} 
ioFDirIndex: INTEGER; {index} 
ioFlAttrib: SignedByte; {file attributes} 
ioFlVersNum: SignedByte; {version number} 
ioFlFndrinfo: FiInfo; {information used by the Finder} 
ioDirID: LONGINT; {directory ID or file number} 
ioFlStBlk: INTEGER; {first allocation block of data fork} 
ioFlLgLen: LONGINT; {logical end-of-file of data fork} 
ioFlPyLen: LONGINT; {physical end-of-file of data fork} 
ioFLRStBLk: INTEGER; {first allocation block of resource fork} 
ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} 
ioFLRPyLen: LONGINT; {physical end-of-file of resource fork} 
ioFlCrDat: LONGINT; {date and time of creation} 
ioFlMdDat: LONGINT) ; {date and time of last modification} 


IOFDirIndex can be used with the PBGetFInfo and PBHGetFInfo to index through the 
files in a given directory. 


Warning: When used with GetFileInfo, ioFDirIndex will index only the files 
in a directory. To index both files and directories, you can use 
ioFDirIndex with PBGetCatInfo. 


IOFlAttrib contains the following file attributes: 
Bit Meaning 


Set if file is locked 

Set if resource fork is open 

Set if data fork is open 

Set if a directory 

Set if file (either fork) is open 


NBWNO 


When passed to a routine, ioDirID contains a directory ID; it can be used to 
refer to a directory or, in conjuction with a partial pathname from that 
directory, to other files and directories. If both a directory ID and a working 
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directory reference number are provided, the directory ID is used to identify 
the directory on the volume indicated by the working directory reference number. 
In other words, a directory ID specified by the caller will override the working 
directory referred to by the working directory reference number. If you don't 
want this to happen, you can set ioDirID to 0. (If no directory is specified 
through a working directory reference number, the root directory ID will be 
used. ) 


When returned from a routine, ioDirID contains the file number of a file; most 
programmers needn't be concerned with file numbers, but those interested can 
read the section "Data Organization on Volumes". 


IOFLStBLk and ioFlLRStBlk contain 0 if the file's data or resource fork is empty, 
respectively; they're used only with flat volumes. The date and time in the 
ioFlCrDat and ioFlMdDat fields are specified in seconds since midnight, 

January 1, 1904. 

VolumeParam Variant (ParamBlockRec) 


When you call GetVolInfo, you'll use the volumeParam variant of ParamBlockRec: 


volumeParam: 
(filler2: LONGINT; {not used} 
ioVolIndex: INTEGER; {index} 
ioVCrDate: LONGINT; {date and time of initialization} 
LoVLSBkUp: LONGINT; {date and time of last modification} 
ioVAtrb: INTEGER; {volume attributes} 
ioVNmF 1s: INTEGER; {number of files in root directory} 
ioVDirSt: INTEGER; {first block of directory} 
ioVBLLn: INTEGER; {length of directory in blocks} 
ioVNmMALBLks: INTEGER; {number of allocation blocks} 
ioVALBLkSiz: LONGINT; {size of allocation blocks} 
ioVCLpSiz: LONGINT; {number of bytes to allocate} 
ioALBLSt: INTEGER; {first block in volume block map} 
ioVNxtFNum: LONGINT; {next unused file number} 
ioVFrBlk: INTEGER) ; {number of unused allocation blocks} 


IOVolIndex can be used to index through all the mounted volumes; using an index 
of 1 accesses the first volume mounted, and so on. (For more information on 
indexing, see the section "Indexing" above. ) 


IOVLSBkUp contains the date and time the volume information was last modified 
(this is not necessarily when it was flushed). (This field is not modified when 
information is written to a file.) 


Note: The name ioVLSBkUp is actually a misnomer; this field has always 
contained the date and time of the last modification to the volume, 
not the last backup. 


Most programmers needn't be concerned with the remaining parameters, but 
interested programmers can read the section "Data Organization on Volumes". 


VolumeParam Variant (HParamBlockRec) 


When you call HGetVInfo and SetVolInfo, you'll use the volumeParam variant of 
HParamBlockRec. This is a superset of the volumeParam variant of ParamBlockRec; 
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the names and functions of certain fields have been changed, and new fields have 
been added: 


volumeParam: 
(filler2: LONGINT; {not used} 
ioVolIndex: INTEGER; {index} 
ioVCrDate: LONGINT; {date and time of initialization} 
ioVLsMod: LONGINT; {date and time of last modification} 
ioVAtrb: INTEGER; {volume attributes} 
ioVNmF 1s: INTEGER; {number of files in root directory} 
ioVBitMap: INTEGER; {first block of volume bit map} 
ioAllocPtr: INTEGER; {block at which next new file starts} 
ioVNmMALBLks: INTEGER; {number of allocation blocks} 
ioVALBLkSiz: LONGINT; {size of allocation blocks} 
ioVCLpSiz: LONGINT; {number of bytes to allocate} 
ioALBLSt: INTEGER; {first block in volume block map} 
ioVNxtCNID: LONGINT; {next unused file number} 
ioVFrBlk: INTEGER; {number of unused allocation blocks} 
ioVSigWord: INTEGER; {volume signature} 
ioVDrvinfo: INTEGER; {drive number} 
ioVDRefNum: INTEGER; {driver reference number} 
ioVFSID: INTEGER; {file system handling this volume} 
ioVBkUp: LONGINT; {date and time of last backup} 
ioVSeqNum: INTEGER; {used internally} 
ioVWrCnt LONGINT; {volume write count} 
ioVFilCnt: LONGINT; {number of files on volume} 
ioVDirCnt: LONGINT; {number of directories on volume} 


ioVFndrinfo: ARRAY[1..8] OF LONGINT); {information used by the Finder} 


IOVolIndex can be used to index through all the mounted volumes; using an index 
of 1 accesses the first volume mounted, and so on. (For more information on 
indexing, see the section "Indexing" above. ) 


IOVLsMod contains the date and time the volume information was last modified 
(this is not necessarily when it was flushed). (This field is not modified when 
information is written to a file.) 


Note: IOVLsMod replaces the field ioVLSBkUp in ParamBlockRec. The name 
ioVLSBkUp was actually a misnomer; this field has always contained 
the date and time of the last modification, not the last backup. 
Another field, ioVBkUp, contains the date and time of the last backup. 


IOVClpSiz can be used to set the volume clump size in bytes; it's used for files 
that don't have a clump size defined as part of their file information in the 
catalog. To promote file contiguity and avoid fragmentation, space is allocated 
to a file not in allocation blocks but in clumps. A clump is a group of 
contiguous allocation blocks. The clump size is always a multiple of the 
allocation block size; it's the minimum number of bytes to allocate each time 
the Allocate function is called or the end-of-file is reached during the Write 
routine. 


IOVSigWord contains a signature word identifying the type of volume; it's $D2D7 
for flat directory volumes and $4244 for hierarchical directory volumes. The 
drive number of the drive containing the volume is returned in ioDrvInfo. For 
on-line volumes, ioVDRefNum returns the reference number of the I/0 driver for 
the drive identified by ioDrvinfo. 
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IOVFSID is the file-system identifier. It indicates which file system is 
servicing the volume; it's 0 for File Manager volumes and nonzero for volumes 
handled by an external file system. 


IOVBkUp specifies the date and time the volume was last backed up (it's 0 if 
never backed up). 


IOVNmFls contains the number of files in the root directory. IOVFilCnt contains 
the total number of files on the volume, while ioVDirCnt contains the total 
number of directories (not including the root directory). 


Most programmers needn't be concerned with the other parameters, but interested 


programmers can read the section "Data Organization on Volumes". 


HParamBlockRec, described above, has been extended to support a shared 
environment with the addition of AccessParam, ObjParam, CopyParam, and 


wDParam, as shown below. (The complete HParamBlockRec data type is shown in the 
summary. ) 
AccessParam: 
(filler3: INTEGER; 
ioDenyModes: INTEGER; {access rights data} 
filler4: INTEGER; 
fillers: Signed Byte; 
ioACUser: Signed Byte; {access rights for directory only} 
filler6: LONGINT; 
ioACOwnerID: LONGINT; {owner ID} 
ioACGroupID: LONGINT; {group ID} 
ioACAccess: LONGINT); faccess rights} 
ObjParam: 
(filler7: INTEGER; 
io0bjType: INTEGER; {function code} 
ioObjNamePtr: Ptr; {ptr to returned creator/group name} 
ioObjID: LONGINT; {creator/group ID} 
ioReqCount: LONGINT; {size of buffer area} 
ioActCount: LONGINT); {length of vol parms data} 
CopyParam: 
(ioDstVRefNum: INTEGER; {destination vol identifier} 
fillers: INTEGER; 
ioNewName: Ptr; {ptr to destination pathname} 
ioCopyName: Ptr; {ptr to optional name} 
ioNewDirID: LONGINT); {destination directory ID} 
WDParam: 
(filler9: INTEGER; 
iowDIndex: INTEGER; 
ioWDProcID: LONGINT; 
iowDVRefNum: INTEGER; 
fillerlo0: INTEGER; 
fillerll: LONGINT; 
fillerl2: LONGINT; 
fillerl3: LONGINT; 
iowDDirID: LONGINT) ; 
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CInfoPBRec 


The routines GetCatInfo and SetCatInfo are used for getting and setting 
information about the files and directories within a directory. With files, 
you'll use the following 19 additional fields after the standard eight fields in 
the parameter block record CInfoPBRec: 


ioFRefNum: INTEGER; {path reference number} 
ioFVersNum: SignedByte; {version number} 
fillerl: SignedByte; {not used} 
ioFDirIndex: INTEGER; {index} 
ioFlAttrib: SignedByte; {file attributes} 
filler2: SignedByte; {not used} 

hFileInfo: 
(ioFlFndrinfo: FInfo; {information used by the Finder} 
ioDirID: LONGINT; {directory ID or file number} 
ioFlStBlk: INTEGER; {first allocation block of data fork} 
ioFlLgLen: LONGINT; {logical end-of-file of data fork} 
ioFlPyLen: LONGINT; {physical end-of-file of data fork} 
ioFLRStBLk: INTEGER; {first allocation block of resource fork} 
ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} 
ioFlRPyLen: LONGINT; {physical end-of-file of resource fork} 
ioFlCrDat: LONGINT; {date and time of creation} 
ioFlMdDat: LONGINT; {date and time of last modification} 
ioFlBkDat: LONGINT; {date and time of last backup} 
ioFlXFndrinfo: FXInfo; {additional information used by the Finder} 
ioFlParID: LONGINT; {file's parent directory ID (integer)} 
ioFlClpSiz: LONGINT) ; {file's clump size} 


eeeClick on the X-Ref button, and refer to Technical Note #69.+e« 


IOFDirIndex can be used with the function PBGetCatInfo to index through the 
files and directories in a given directory. For each iteration of the function, 
you can determine whether it's a file or a directory by testing bit 4 (the fifth 
least significant bit) of ioFlAttrib. You can test for a directory by using the 
Toolbox Utilities BitTst function in the following manner (remember, the Toolbox 
Utilities routines reverse the standard 68000 notation): 


BitTst (@myCInfoRec.ioFlAttrib, 3) 

IOFlAttrib contains the following attributes: 
Bit Meaning 

Set if file is locked 

Set if resource fork is open 

Set if data fork is open 


Set if a directory 
Set if file (either fork) is open 


NBWNO 


When passed to a routine, ioDirID contains a directory ID; it can be used to 
refer to a directory or, in conjuction with a partial pathname from that 
directory, to other files and directories. If both a directory ID and a working 
directory reference number are provided, the directory ID is used to identify 
the directory on the volume indicated by the working directory reference number. 
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In other words, a directory ID specified by the caller will override the working 
directory referred to by the working directory reference number. If you don't 
want this to happen, you can set ioDirID to 0. (If no directory is specified 
through a working directory reference number, the root directory ID will be 
used. ) 


Warning: With files, ioDirID returns the file number of the file; when 
indexing with GetCatInfo, you'll need to reset this field for 
each iteration. 


IOFLStBLk and ioFlLRStBlk contain 0 if the file's data or resource fork is empty, 
respectively; they're used only with flat volumes. The date and time in the 
ioFlCrDat, ioFlMdDat, and ioFlBkDat fields are specified in seconds since 
midnight, January 1, 1904. 


IOFlParID contains the directory ID of the file's parent. IOFlClpSiz is the 
clump size to be used when writing the file; if it's 0, the volume's clump size 
is used when the file is opened. 


With directories, you'll use the following 14 additional fields after the 
standard eight fields in the parameter block record CInfoPBRec: 


ioFRefNum: INTEGER; {file reference number} 
ioFVersNum SignedByte; {version number} 
fillerl: SignedByte; {not used} 
ioFDirIndex: INTEGER; {index} 
ioFlAttrib: SignedByte; {file attributes} 
filler2: SignedByte; {not used} 
dirInfo: 
(ioDrUsrwds: Dinfo; {information used by the Finder} 
ioDrDirID: LONGINT; {directory ID} 
ioDrNmF 1s: INTEGER; {number of files in directory} 
filler3: ARRAY[1..9] OF INTEGER; {not used} 
ioDrCrDat: LONGINT; {date and time of creation} 
ioDrMdDat: LONGINT; {date and time of last modification} 
ioDrBkDat: LONGINT; {date and time of last backup} 
ioDrFndrinfo: DXInfo; {additional information used by the Finder} 
ioDrParID: LONGINT) ; {directory's parent directory ID (integer) } 


IOFDirIndex can be used with the function PBGetCatInfo to index through the 
files and directories in a given directory. For each iteration of the function, 
you can determine whether it's a file or a directory by testing bit 4 of 
ioFlAttrib. 


When passed to a routine, ioDrDirID contains a directory ID; it can be used to 
refer to a directory or, in conjuction with a partial pathname from that 
directory, to other files and directories. If both a directory ID and a working 
directory reference number are provided, the directory ID is used to identify 
the directory on the volume indicated by the working directory reference number. 
In other words, a directory ID specified by the caller will override the working 
directory referred to by the working directory reference number. If you don't 
want this to happen, you can set ioDirID to 0. (If no directory is specified 
through a working directory reference number, the root directory ID will be 
used. ) 


With directories, ioDrDirID returns the directory ID of the directory. 
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IODrNmFls is the number of files and directories contained in this directory 
(the valence of the directory). 


The date and time in the ioDrCrDat, ioDrMdDat, and ioDrBkDat fields are 
specified in seconds since midnight, January 1, 1904. 


I0DrParID contains the directory ID of the directory's parent. 
CMovePBRec 
When you call CatMove to move files or directories into a different directory, 


you'll use the following six additional fields after the standard eight fields 
in the parameter block record CMovePBRec: 


fillerl: LONGINT; {not used} 

ioNewName: StringPtr; {name of new directory} 

filler2: LONGINT; {not used} 

ioNewDirID: LONGINT; {directory ID of new directory} 
filler3: ARRAY[1..2] OF LONGINT; {not used} 

ioDirID: LONGINT) ; {directory ID of current directory} 


IONewName and ioNewDirID specify the name and directory ID of the directory to 
which the file or directory is to be moved. IODirID (used in conjuntion with the 
ioVRefNum and ioNamePtr) specifies the current directory ID of the file or 
directory to be moved. 


WDPBRec 
When you call the routines that open, close, and get information about working 


directories, you'll use the following six additional fields after the standard 
eight fields in the parameter block record WDPBRec: 


fillerl: INTEGER; {not used} 

iowDIndex: INTEGER; {index} 

ioWDProcID: LONGINT; {working directory user identifier} 
iowDVRefNum: INTEGER; {working directory's volume reference number} 
filler2: ARRAY[1..7] OF INTEGER; {not used} 

iowDDirID: LONGINT) ; {working directory's directory ID} 


IOWDIndex can be used with the function PBGetWDInfo to index through the current 
working directories. 


IOWDProcID is an identifier that's used to distinguish between working 
directories set up by different users; you should use the application's 
Signature (discussed in the Finder Interface chapter) as the ioWDProcID. 


Routine Descriptions 

Each routine description includes the low-level Pascal form of the call and the 
routine's assembly-language macro. A list of the parameter block fields used by 
the call is also given. 


Assembly-language note: The field names given in these descriptions are 
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those found in the Pascal parameter block records; 
see the summary at the end of this chapter for the 
names of the corresponding assembly-language offsets. 
(The names for some offsets differ from their Pascal 
equivalents, and in certain cases more than one name 
for the same offset is provided. ) 


The number next to each parameter name indicates the byte offset of the 
parameter from the start of the parameter block pointed to by register AQ; only 
assembly-language programmers need be concerned with it. An arrow next to each 
parameter name indicates whether it's an input, output, or input/output 
parameter: 


Arrow Meaning 
--> Parameter is passed to the routine 
<-- Parameter is returned by the routine 
<-> Parameter is passed to and returned by the routine 


Warning: You must pass something (even if it's NIL) for each of the 
parameters shown for a particular routine; if you don't, the 
File Manager may use garbage that's sitting at a particular offset. 


Initializing the File I/0 Queue 
PROCEDURE FInitQueue; 
Trap macro _InitQueue 


FInitQueue clears all queued File Manager calls except the current one.Accessing 
Volumes 


To get the volume reference number of a volume, given the path reference number 
of a file on that volume, both Pascal and assembly-language programmers can call 
the high-level File Manager function GetVRefNum. Assembly-language programmers 
may prefer calling the function GetFCBInfo (described below in the section "Data 
Structures in Memory"). 


FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr; 


Trap macro _MountVol 
Parameter block 
ces 16 ioResult word 
<-> 22 ioVRefNum word 


PBMountVol mounts the volume in the drive specified by ioVRefNum, and returns a 
volume reference number in ioVRefNum. If there are no volumes already mounted, 
this volume becomes the default volume. PBMountVol is always executed 
synchronous Ly. 


Note: When mounting hierarchical volumes, PBMountVol opens two files 
needed for maintaining file directory and file mapping information. 
PBMountVol can fail if there are no access paths available for these 
two files; it will return tmfoErr as its function result. 


Result codes noErr No error 
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badMDBErr Bad master directory block 
extFSErr External file system 

ioErr I/O error 

memFullErr Not enough room in heap zone 
noMacDskErr Not a Macintosh disk 


nsDrvErr No such drive 
paramErr Bad drive number 
tmfoErr Too many files open 


volOnLinErr Volume already on-line 


FUNCTION PBGetVInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _GetVolInfo 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
<-> 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
--> 28 ioVolIndex word 
<-- 30 ioVCrDate long word 
<-- 34 ioVLsBkUp long word 
<-- 38 ioVAtrb word 
<-- 40 ioVNmFLs word 
<-- 42 ioVDirSt word 
<-- 44 ioVBLLn word 
<-- 46 ioVNmMALBLks — word 
<-- 48 ioVALBLkSiz — long word 
<-- 52 ioVCLpSiz long word 
<-- 56 ioALBLSt word 
<-- 58 ioVNxtFNum long word 
<-- 62 ioVFrBlk word 


PBGetVInfo returns information about the specified volume. If ioVolIndex is 
positive, the File Manager attempts to use it to find the volume; for instance, 
if ioVolIndex is 2, the File Manager will attempt to access the second mounted 
volume. If ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum 
in the standard way (described in the section "Specifying Volumes, Directories, 
and Files") to determine which volume. If ioVolIndex is 0, the File Manager 
attempts to access the volume by using ioVRefNum only. The volume reference 
number is returned in ioVRefNum, and a pointer to the volume name is returned in 
ioNamePtr (unless ioNamePtr is NIL). 


If a working directory reference number is passed in ioVRefNum (or if the 
default directory is a subdirectory), the number of files and directories in the 
specified directory (the directory's valence) will be returned in ioVNmFls. 
Also, the volume reference number won't be returned; ioVRefNum will still 
contain the working directory reference number. 


Warning: IOVNmALBLks and ioVFrBlks, which are actually unsigned integers, 
are clipped to 31744 ($7C00) regardless of the size of the volume. 


Result codes noErr No error 
nsvErr No such volume 
paramErr No default volume 
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FUNCTION PBHGetVInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _HGetVInfo 
Parameter block 

--> 12 ioCompletion pointer 
<-- 16 ioResult word 

<-> 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 

--> 28 ioVolIndex word 

<-- 30 ioVCrDate long word 
<-- 34 ioVLsMod long word 
<-- 38 ioVAtrb word 

<-- 40 ioVNmFLs word 

<2: 42 ioVBitMap word 

<-- 44 ioVALlocPtr word 

<-- 46 ioVNmMALBLks — word 

<-- 48 ioVALBLkSiz long word 
<-- 52 ioVCLpSiz long word 
<-- 56 ioALBLSt word 

<-- 58 ioVNxtFNum long word 
<-- 62 ioVFrBlk word 

<-- 64 ioVSigWord word 

<-- 66 ioVDrvinfo word 

<-- 68 ioVDRefNum word 

<-- 70 ioVFSID word 

<-- 72 ioVBkUp long word 
<-- 76 ioVSeqNum word 

<-- 78 ioVWrCnt long word 
<-- 82 ioVFilCnt long word 
<-- 86 ioVDirCnt long word 
<-- 90 ioVFndrinfo 32 bytes 


PBHGetVInfo is similar in function to PBGetVInfo but returns a larger parameter 
block. In addition, PBHGetVInfo always returns the volume reference number in 
ioVRefNum (regardless of what was passed in). Also, ioVNmALBLks and ioVFrBlks 
are not clipped as they are by PBGetVInfo. 


Result codes noErr No error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION PBSetVInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


eeeClick on the X-Ref button, and refer to Technical Note #204, eee 


Trap macro _SetVoliInfo 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 30 ioVCrDate long word 
--> 34 ioVLsMod long word 
--> 38 ioVAtrb word 
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--> 52 ioVClLpSiz long word 
--> 72 ioVBkUp long word 
--> 76 ioVSeqNum word 

--> 90 ioVFndriInfo 32 bytes 


PBSetVInfo lets you modify information about volumes. A pointer to a new name 
for the volume can be specified in ioNamePtr. The date and time of the volume's 
creation and modification can be set with ioVCrDate and ioVLsMod respectively. 
Only bit 15 of ioVAtrb can be changed; setting it locks the volume. 


Note: The volume cannot be specified by name; you must use either the 
volume reference number or the drive number. 


Warning: PBSetVInfo operates only with the hierarchical version of the 
File Manager; if used on a Macintosh equipped only with the 
64K ROM version of the File Manager, it will generate a system error. 


Result codes noErr No error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION PBGetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _GetVol 

Parameter block 
--> 12 ioCompletion pointer 
<o 16 ioResult word 
<-- 18 ioNamePtr pointer 
<-- 22 ioVRefNum word 


PBGetVol returns a pointer to the name of the default volume in ioNamePtr 
(unless ioNamePtr is NIL) and its volume reference number in ioVRefNum. If a 
default directory was set with a previous PBSetVol call, a pointer to its name 
will be returned in ioNamePtr and its working directory reference number in 
ioVRefNum. 


Result codes noErr No error 
nsvErr No default volume 


FUNCTION PBHGetVol (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 


Trap macro _HGetVol 

Parameter block 
--> 12 ioCompletion pointer 
<2 16 ioResult word 
<-- 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
<-- 28 ioWDProcID long word 
<a. 32 ioWDVRefNum word 
<-- 48 iowDDirID long word 


PBHGetVol returns the default volume and directory last set by either a PBSetVol 
or a PBHSetVol call. The reference number of the default volume is returned in 
ioVRefNum. 
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Warning: IOVRefNum will return a working directory reference number 
(instead of the volume reference number) if, in the last call 
to PBSetVol or PBHSetVol, a working directory reference number 
was passed in this field. 


The volume reference number of the volume on which the default directory exists 
is returned in ioWDVRefNum. The directory ID of the default directory is 
returned in ioWDDirID. 


Result codes noErr No error 
nsvErr No default volume 


FUNCTION PBSetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _SetVol 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


PBSetVol sets the default volume to the mounted volume specified by ioNamePtr or 
ioVRefNum. On hierarchical volumes, PBSetVol also sets the root directory as the 
default directory. 


Result codes noErr No error 
bdNamErr Bad volume name 
nsvErr No such volume 


paramErr No default volume 
FUNCTION PBHSetVol (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 


eeeClick on the X-Ref button, and refer to Technical Note #140, eee 


Trap macro _HSetVol 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 48 iowDDirID long word 


PBHSetVol sets both the default volume and the default directory. The default 
directory to be used can be specified by either a volume reference number or a 
working directory reference number in ioVRefNum, a directory ID in ioWDDirID, or 
a pointer to a pathname (possibly NIL) in ioNamePtr. 


Note: Both the default volume and the default directory are used in 
calls made with no volume name and a volume reference number of zero. 


Result codes noErr No error 
nsvErr No default volume 
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FUNCTION PBFlushVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _FlushVolt 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes descriptive 
information about the volume, the contents of the associated volume buffer, and 
all access path buffers for the volume (if they've changed since the last time 
PBFlushVol was called). 


Note: The date and time of the last modification to the volume are set 
when the modification is made, not when the volume is flushed. 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 


ioErr I/0 error 
nsDrvErr No such drive 
nsvErr No such volume 


paramErr No default volume 


FUNCTION PBUnmountVol (paramBlock: ParmBlkPtr) : OSErr; 


Trap macro _UnmountVol 
Parameter block 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 


--> 22 ioVRefNum word 


PBUnmountVol unmounts the volume specified by ioNamePtr or ioVRefNum, by calling 
PBFlushVol to flush the volume, closing all open files on the volume, and 
releasing the memory used for the volume. PBUnmountVol is always executed 
synchronous Ly. 


Warning: Don't unmount the startup volume. 


Note: Unmounting a volume does not close working directories; to release 
the memory allocated to a working directory, call PBClosewWD. 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 


ioErr I/O error 
nsDrvErr No such drive 
nsvErr No such volume 


paramErr No default volume 
FUNCTION PBOffLine (paramBlock: ParmBlkPtr) : OSErr; 


Trap macro _OffLine 
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Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


PBOffLine places off-line the volume specified by ioNamePtr or ioVRefNum, by 
calling PBFlushVol to flush the volume and releasing all the memory used for the 
volume except for the volume control block. PBOffLine is always executed 
synchronous Ly. 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 


ioErr I/O error 
nsDrvErr No such drive 
nsvErr No such volume 


paramErr No default volume 


FUNCTION PBEject (paramBlock: ParmBlkPtr) : OSErr; 


Trap macro Eject 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


PBEject flushes the volume specified by ioNamePtr or ioVRefNum, places it 
off-line, and then ejects the volume. 


Assembly-language note: You may invoke the macro Eject asynchronously; 
the first part of the call is executed synchronously, 
and the actual ejection is executed asynchronously. 


Result codes noErr No error 
bdNamErr Bad volume name 
extFSErr External file system 


ioErr I/O error 
nsDrvErr No such drive 
nsvErr No such volume 


paramErr No default volume 
Accessing Files 


FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _ Open 

Parameter block 
--> 12 ioCompletion pointer 
<s- 16 ioResult word 
--> 18 ioNamePtr pointer 
225 22 ioVRefNum word 
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<-- 24 ioRefNum word 


--> 26 ioVersNum byte 
--> 27 ioPermssn byte 
--> 28 ioMisc pointer 


PBOpen creates an access path to the file having the name pointed to by 
ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume 
specified by ioVRefNum. A path reference number is returned in ioRefNum. 


IOMisc either points to a portion of memory (522 bytes) to be used as the access 
path's buffer, or is NIL if you want the volume buffer to be used instead. 


Warning: All access paths to a single file that's opened multiple times 
should share the same buffer so that they will read and write 
the same data. 


IOPermssn specifies the path's read/write permission. A path can be opened for 
writing even if it accesses a file on a locked volume, and an error won't be 
returned until a PBWrite, PBSetEOF, or PBAllocate call is made. 


If you attempt to open a locked file for writing, PBOpen will return permErr as 
its function result. If you request exclusive read/write permission but another 
access path already has write permission (whether write only, exclusive 
read/write, or shared read/write), PBOpen will return the reference number of 
the existing access path in ioRefNum and opWrErr as its function result. 
Similarly, if you request shared read/write permission but another access path 
already has exclusive read/write permission, PBOpen will return the reference 
number of the access path in ioRefNum and opWrErr as its function result. 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
opWrErr File already open for writing 
permErr Attempt to open locked file for writing 
tmfoErr Too many files open 


FUNCTION PBHOpen (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _HOpen 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 

<-- 24 ioRefNum word 

--> 27 ioPermssn byte 

--> 28 ioMisc pointer 
--> 48 ioDirID long word 


PBHOpen is identical to PBOpen except that it accepts a directory ID in ioDirID. 


Result codes noErr No error 
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bdNamErr Bad file name 
dirNFErr Directory not found or incomplete pathname 


extFSErr External file system 

fnfErr File not found 

ioErr I/O error 

nsvErr No such volume 

opWrErr File already open for writing 

permErr Attempt to open locked file for writing 
tmfoErr Too many files open 


FUNCTION PBOpenRF (paramBlock: ParmBlkPtr; async: BOOLEAN) OSErr; 


Trap macro _OpenRF 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
> 22 ioVRefNum word 
<-- 24 ioRefNum word 
--> 26 ioVersNum byte 
--> 27 ioPermssn byte 
--> 28 ioMisc pointer 


PBOpenRF is identical to PBOpen, except that it opens the file's resource fork 
instead of its data fork. 

Note: Normally you should access a file's resource fork through the 
routines of the Resource Manager rather than the File Manager. 
PBOpenRF doesn't read the resource map into memory; it's really 
only useful for block-level operations such as copying files. 


noErr No error 
bdNamErr Bad file name 


Result codes 


extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
opWrErr File already open for writing 
permErr Attempt to open locked file for writing 
tmfoErr Too many files open 
FUNCTION PBHOpenRF (paramBlock: HParmBlkPtr; async: BOOLEAN) OSErr; 
Trap macro _HOpenRF 
Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-- 24 ioRefNum word 
--> 27 ioPermssn byte 
-2> 28 ioMisc pointer 
--> 48 ioDirID long word 
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PBHOpenRF is identical to PBOpenRF except that it accepts a directory ID in 
ioDirID. 


Result codes noErr No error 
bdNamErr Bad file name 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
opWrErr File already open for writing 
permErr Attempt to open locked file for writing 
tmfoErr Too many files open 


FUNCTION PBLockRange (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


eeeClick on the X-Ref button, and refer to Technical Note #186. ¢ee 


Trap macro _LockRng 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 
--> 36 ioReqCount long word 
=2> 44 ioPosMode word 


--> 46 ioPosOffset long word 


On a file opened with a shared read/write permission, PBLockRange is used in 
conjunction with PBRead and PBWrite to lock a certain portion of the file. 
PBLockRange uses the same parameters as both PBRead and PBWrite; by calling it 
immediately before PBRead, you can use the information present in the parameter 
block for the PBRead call. 


When you're finished with the data (typically after a call to PBWrite), be sure 
to call PBUnlockRange to free up that portion of the file for subsequent PBRead 
calls. 


Warning: PBLockRange operates only with the hierarchical version of the 
File Manager; if used on a Macintosh equipped only with the 64K 
ROM version of the File Manager, it will generate a system error. 


Result codes noErr No error 
eofErr End-of-file 
extFSErr External file system 
fnOpnErr File not open 
ioErr I/O error 
paramErr Negative ioReqCount 
rfNumErr Bad reference number 


FUNCTION PBUnlockRange (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _UnlockRng 


Parameter block 
--> 12 ioCompletion pointer 
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<-- 16 
--> 24 
ated 36 
--> 44 
--> 46 


ioResult 
ioRefNum 
ioReqCount 
ioPosMode 


ioPosOf fset 


word 
word 
long word 
word 
long word 


PBUnlockRange is used in conjunction with PBRead and PBWrite to unlock a certain 
portion of a file that you locked with PBLockRange. 


Warning: PBUnlockRange operates only with the hierarchical version of 
the File Manager; if used on a Macintosh equipped only with 
the 64K ROM version of the File Manager, it will generate a 
system error. 


Result codes 


noErr 
eofErr 
extFSErr 
fnOpnErr 
ioErr 
paramErr 
rfNumErr 


No error 

End-of-file 

External file system 
File not open 

I/O error 

Negative ioReqCount 
Bad reference number 


FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) 


Trap macro 


Parameter block 


--> 12 
<-- 16 
--> 24 
--> 32 
--> 36 
<-- 40 
--> 44 
<-> 46 


_ Read 


ioCompletion pointer 


ioResult 
ioRefNum 
ioBuf fer 
ioReqCount 
ioActCount 
ioPosMode 
ioPosOffset 


word 

word 
pointer 
long word 
long word 
word 

long word 


OSErr; 


PBRead attempts to read ioReqCount bytes from the open file whose access path is 
specified by ioRefNum, and transfer them to the data buffer pointed to by 
ioBuffer. The position of the mark is specified by ioPosMode and ioPosOffset. If 
you try to read past the logical end-of-file, PBRead moves the mark to the end- 
of-file and returns eofErr as its function result. After the read is completed, 
the mark is returned in ioPosOffset and the number of bytes actually read is 
returned in ioActCount. 


Result codes 


noErr 
eofErr 
extFSErr 
fnOpnErr 
ioErr 
paramErr 
rfNumErr 


No error 

End-of-file 

External file system 
File not open 

I/O error 

Negative ioReqCount 
Bad reference number 


FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) 


Trap macro 


_Write 


OSErr; 


@ SpInside Macintosh * Version 1.0 * November 1989 « Apple Computer 
THE FILE 


MANAGER ¢ 71 of 150 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

--> 24 ioRefNum word 

--> 32 ioBuffer pointer 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 
--> 44 ioPosMode word 

<-> 46 ioPosOffset long word 


PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and 
attempts to write them to the open file whose access path is specified by 
ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. 
After the write is completed, the mark is returned in ioPosOffset and the number 
of bytes actually written is returned in ioActCount. 


Result codes noErr No error 
dskFulErr Disk full 
flckdErr File locked 
fnOpnErr File not open 
ioErr I/O error 
paramErr Negative ioReqCount 
posErr Attempt to position before start of file 
rfNumErr Bad reference number 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
wrPermErr Read/write permission doesn't allow writing 


FUNCTION PBGetFPos (paramBlock: 


Trap macro 


Parameter block 


GetFPos 


ParmBLkPtr; async: BOOLEAN) OSErr; 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

--> 24 ioRefNum word 

<-- 36 ioReqCount long word 
<-- 40 ioActCount long word 
<-- 44 ioPosMode word 

<-- 46 ioPosOffset long word 


PBGetFPos returns, in ioPosOffset, the mark of the open file whose access path 
It sets ioReqCount, ioActCount, and ioPosMode to 0. 


is specified by ioRefNum. 


Result codes 


FUNCTION PBSetFPos (paramBlock: 


Trap macro 


noErr 
extFSErr 
fnOpnErr 
gfpErr 
ioErr 
rfNumErr 


SetFPos 


Parameter block 
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No error 

External file system 

File not open 

Error during GetFPos 

I/0 error 

Bad reference number 

BOOLEAN) 


ParmBLkPtr; async: OSErr; 


THE 


FILE 


--> 12 ioCompletion pointer 


<-- 16 ioResult word 
--> 24 ioRefNum word 
--> 44 ioPosMode word 
<-> 46 ioPosOffset long word 


PBSetFPos sets the mark of the open file whose access path is specified by 
ioRefNum to the position specified by ioPosMode and ioPosOffset. The position at 
which the mark is actually set is returned in ioPosOffset. If you try to set the 
mark past the logical end-of-file, PBSetFPos moves the mark to the end-of-file 
and returns eofErr as its function result. 


Result codes noErr No error 
eofErr End-of-file 
extFSErr External file system 
fnOpnErr File not open 


ioErr I/O error 
posErr Attempt to position before start of file 
rfNumErr Bad reference number 
FUNCTION PBGetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _GetEOF 
Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 
<-- 28 ioMisc long word 


PBGetEOF returns, in ioMisc, the logical end-of-file of the open file whose 
access path is specified by ioRefNum. 


Result codes noErr No error 
extFSErr External file system 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 


FUNCTION PBSetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _SetEOF 
Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
22> 24 ioRefNum word 
--> 28 ioMisc long word 


PBSetEOF sets the logical end-of-file of the open file, whose access path is 
specified by ioRefNum, to ioMisc. If you attempt to set the logical end-of-file 
beyond the physical end-of-file, another allocation block is added to the file; 
if there isn't enough space on the volume, no change is made, and PBSetEOF 
returns dskFulErr as its function result. If ioMisc is 0, all space occupied by 
the file on the volume is released. 
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Result codes noErr No error 
dskFulErr Disk full 
extFSErr External file system 
flLckdErr File locked 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
wrPermErr Read/write permission doesn't allow writing 


FUNCTION PBALlocate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _Allocate 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
==> 24 ioRefNum word 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 


PBALlocate adds ioReqCount bytes to the open file whose access path is specified 
by ioRefNum, and sets the physical end-of-file to one byte beyond the last block 
allocated. The number of bytes actually allocated is rounded up to the nearest 
multiple of the allocation block size, and returned in ioActCount. If there 
isn't enough empty space on the volume to satisfy the allocation request, 
PBALlocate allocates the rest of the space on the volume and returns dskFulErr 
as its function result. 


Note: Even if the total number of requested bytes is unavailable, 
PBALlocate will allocate whatever space, contiguous or not, is 
available. To force the allocation of the entire requested space 
as a contiguous piece, call PBALlocContig instead. 


Result codes noErr No error 
dskFulErr Disk full 
flLckdErr File locked 
fnOpnErr File not open 
ioErr I/O error 
rfNumErr Bad reference number 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
wrPermErr Read/write permission doesn't allow writing 


FUNCTION PBALlocContig (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _AllocContig 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 
--> 36 ioReqCount long word 
<-- 40 ioActCount long word 
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PBALlocContig is identical to PBAllocate except that if there isn't enough 
contiguous empty space on the volume to satisfy the allocation request, 
PBALlLocContig will do nothing and will return dskFulErr as its function result. 
If you want to allocate whatever space is available, even when the entire 
request cannot be filled as a contiguous piece, call PBALlocate instead. 


Result codes noErr No error 

dskFulErr Disk full 

flLckdErr File locked 

fnOpnErr File not open 

ioErr I/O error 

rfNumErr Bad reference number 

vLckdErr Software volume lock 

wPrErr Hardware volume lock 

wrPermErr Read/write permission doesn't allow writingFUNCTION 
PBFlushFile (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _FlushFile 

Parameter block 
--> 12 ioCompletion pointer 
<s- 16 ioResult word 
--> 24 ioRefNum word 


PBFlushFile writes the contents of the access path buffer indicated by ioRefNum 
to the volume, and updates the file's entry in the file directory (or in the 
file catalog, in the case of hierarchical volumes). 


Warning: Some information stored on the volume won't be correct 
until PBFlushVol is called. 


Result codes noErr No error 
extFSErr External file system 
fnfErr File not found 
fnOpnErr File not open 
ioErr I/O error 
nsvErr No such volume 


rfNumErr Bad reference number 


FUNCTION PBClose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _Close 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 


PBClose writes the contents of the access path buffer specified by ioRefNum to 
the volume and removes the access path. 


Warning: Some information stored on the volume won't be correct 
until PBFlushVol is called. 


Result codes noErr No error 
extFSErr External file system 
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fnfErr File not found 
fnOpnErr File not open 

ioErr I/O error 

nsvErr No such volume 
rfNumErr Bad reference number 


Creating and Deleting Files and Directories 


FUNCTION PBCreate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _Create 

Parameter block 
--> 12 ioCompletion pointer 
<s- 16 ioResult word 
--> 18 ioNamePtr pointer 
-+5 22 ioVRefNum word 


--> 26 ioFVersNum byte 


PBCreate creates a new file (both forks) having the name pointed to by ioNamePtr 
(and on flat volumes, the version number ioVersNum) on the volume specified by 
ioVRefNum. The new file is unlocked and empty. The date and time of its creation 
and last modification are set to the current date and time. If the file created 
isn't temporary (that is, if it will exist after the application terminates), 
the application should call PBSetFInfo (after PBCreate) to fill in the 
information needed by the Finder. 


Assembly-language note: If a desk accessory creates a file, it should 
always create it in the directory containing the 
system folder. The working directory reference 
number for this directory is stored in the global 
variable BootDrive; you can pass it in ioVRefNum. 


Result codes noErr No error 
bdNamErr Bad file name 
dupFNErr Duplicate file name and version 
dirFulErr File directory full 
extFSErr External file system 


ioErr I/O error 

nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION PBHCreate (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _HCreate 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 48 ioDirID long word 


PBHCreate is identical to PBCreate except that it accepts a directory ID in 
ioDirID. 
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Note: To create a directory instead of a file, call PBDirCreate. 


Result codes noErr No error 
bdNamErr Bad file name 
dupFNErr Duplicate file name and version 
dirFulErr File directory full 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 


ioErr I/0 error 

nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION PBDirCreate (paramBlock: HParmBlkPtr; async: BOOLEAN): OSErr; 


Trap macro _DirCreate 

Parameter block 
--> 12 ioCompletion pointer 
eo 16 ioResult word 
<-> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-> 48 ioDirID long word 


PBDirCreate is identical to PBHCreate except that it creates a new directory 
instead of a file. You can specify the parent of the directory to be created in 
ioDirID; if it's 0, the new directory will be placed in the root directory. The 
directory ID of the new directory is returned in ioDirID. 


Warning: PBDirCreate operates only with the hierarchical version of 
the File Manager; if used on a Macintosh equipped only with 
the 64K ROM version of the File Manager, it will generate a 
system error. 


Result codes noErr No error 
bdNamErr Bad file name 
dupFNErr Duplicate file name and version 
dirFulErr File directory full 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 


ioErr I/0 error 

nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION PBDelete (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _Delete 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


--> 26 ioFVersNum byte 
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PBDelete removes the closed file having the name pointed to by ioNamePtr (and on 


flat volumes, the version number ioVersNum) from the volume pointed to by 
ioVRefNum. PBHDelete can be used to delete an empty directory as well. 


Note: 


Result codes 


FUNCTION PBHDelete (paramBlock: 


Trap macro Z| 
Parameter block 
--> 12 
<-- 16 
--> 18 
--> 22 
--> 48 


PBHDelete is identical to 
ioDirID. PBHDelete can be 


Result codes 


This function will 


delete both forks of the file. 


noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
fBsyErr File busy, directory not empty, or working 
directory control block open 
fLckdErr File locked 
fnfErr File not found 
nsvErr No such volume 
ioErr I/O error 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 
HParmBLkPtr; async: BOOLEAN) OSErr; 
HDelete 
ioCompletion pointer 
ioResult word 
ioNamePtr pointer 
ioVRefNum word 
ioDirID long word 


noErr 
bdNamErr 
dirNFErr 
extFSErr 
fBsyErr 


flckdErr 
fnfErr 
nsvErr 
ioErr 
vLckdErr 
wPrErr 


PBDelete except that it accepts a directory ID in 
used to delete an empty directory as well. 


No error 

Bad file name 

Directory not found or incomplete pathname 
External file system 

File busy, directory not empty, or working 
directory control block open 

File locked 

File not found 

No such volume 

I/O error 

Software volume lock 

Hardware volume lock 


Changing Information About Files and Directories 


FUNCTION PBGetFInfo (paramBlock: 


Trap macro 


Parameter block 
--> 12 
<-- 16 
<-> 18 
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ParmBLkPtr; async: BOOLEAN) OSErr; 
_GetFileInfo 
ioCompletion pointer 
ioResult word 
ioNamePtr pointer 


THE 


FILE 


--> 22 ioVRefNum word 


<-- 24 ioFRefNum word 

--> 26 ioFVersNum byte 

--> 28 ioFDirIndex word 

<-- 30 ioFlAttrib byte 

<-- 31 ioFlVersNum byte 

<-- 32 ioFlFndrinfo 16 bytes 
<-- 48 ioFlNum long word 
<-- 52 ioFlStBlk word 

<-- 54 ioFlLgLen long word 
<-- 58 ioFlPyLen long word 
<-- 62 ioFLRStBLk word 

<-- 64 ioFlRLgLen long word 
<-- 68 ioFlLRPyLen long word 
<-- 72 ioFlCrDat long word 
<-- 76 ioFlMdDat long word 


PBGetFInfo returns information about the specified file. If ioFDirIndex is 
positive, the File Manager returns information about the file whose directory 
index is ioFDirIndex on the volume specified by ioVRefNum. (See the section 
"Data Organization on Volumes" if you're interested in using this method. ) 


Note: If a working directory reference number is specified in ioVRefNum, 
the File Manager returns information about the file whose directory 
index is ioFDirIndex in the specified directory. 


If ioFDirIndex is negative or 0, the File Manager returns information about the 
file having the name pointed to by ioNamePtr (and on flat volumes, the version 
number ioFVersNum) on the volume specified by ioVRefNum. If the file is open, 
the reference number of the first access path found is returned in ioFRefNum, 
and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
fnfErr File not found 
ioErr I/0 error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION PBHGetFInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _HGetFileInfo 

Parameter block 
--> 12 ioCompletion pointer 
25 16 ioResult word 
<-> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-- 24 ioFRefNum word 
--> 28 ioFDirIndex word 
<-- 30 ioFlAttrib byte 
<-- 32 ioFlFndrinfo 16 bytes 
<-> 48 ioDirID long word 
<-- 52 ioFlStBlk word 
<-- 54 ioFlLgLen long word 
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<-- 58 ioFlPyLen long word 


<-- 62 ioFLRStBLk word 

<-- 64 ioFlRLgLen long word 
<-- 68 ioFlLRPyLen long word 
<-- 72 ioFlCrDat long word 
<-- 76 ioFlMdDat long word 


PBHGetFInfo is identical to PBGetFInfo except that it accepts a directory ID in 
ioDirID. 


Result codes noErr No error 
bdNamErr Bad file name 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION PBSetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _SetFileInfo 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


--> 26 ioFVersNum byte 

--> 32 ioFlFndrinfo 16 bytes 
--> 72 ioFlCrDat long word 
--> 76 ioFlMdDat long word 


PBSetFInfo sets information (including the date and time of creation and 
modification, and information needed by the Finder) about the file having the 
name pointed to by ioNamePtr (and on flat volumes, the version number 
ioFVersNum) on the volume specified by ioVRefNum. You should call PBGetFiInfo 
just before PBSetFInfo, so the current information is present in the parameter 
block. 


Result codes noErr No error 
bdNamErr Bad file name 
extFSErr External file system 
flLckdErr File locked 
fnfErr File not found 


ioErr I/O error 

nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION PBHSetFInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _HSetFileInfo 


Parameter block 
--> 12 ioCompletion pointer 
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16 
18 
22 
32 
48 
72 
76 


ioResult 
ioNamePtr 
ioVRefNum 
ioFlFndrin 
ioDirID 
ioFlCrDat 
ioFlMdDat 


PBHSetFiInfo is identical 


ioDirID. 


Result codes 


noErr 
bdNamErr 
dirNFeErr 
extFSErr 
flckdErr 
fnfErr 
ioErr 
nsvErr 
vLckdErr 
wPrErr 


word 
pointer 
word 

fo 16 bytes 
long word 
long word 
long word 


to PBSetFInfo except that it accepts a directory ID in 


No error 

Bad file name 

Directory not found or incomplete pathname 
External file system 

File locked 

File not found 

I/O error 

No such volume 

Software volume lock 

Hardware volume lock 


FUNCTION PBSetFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


Parameter block 


-:> 
aa 
i> 
=+> 
--> 


12 
16 
18 
22 
26 


_SetFilLock 


ioCompletion pointer 


ioResult 
ioNamePtr 
ioVRefNum 
ioFVersNum 


word 
pointer 
word 
byte 


PBSetFLock locks the file having the name pointed to by ioNamePtr (and on flat 
volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. 
Access paths currently in use aren't affected. 


Result codes 


noErr 
extFSErr 
fnfErr 
ioErr 
nsvErr 
vLckdErr 
wPrErr 


No error 

External file system 
File not found 

I/0 error 

No such volume 
Software volume lock 
Hardware volume lock 


FUNCTION PBHSetFLock (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


Parameter block 


12 
16 
18 
22 
48 


_HSetFLock 


ioCompletion pointer 


ioResult 
ioNamePtr 
ioVRefNum 
ioDirID 


word 
pointer 
word 

long word 
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PBHSetFLock is identical to PBSetFLock except that it accepts a directory ID in 
ioDirID. 


Result codes noErr No error 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 
fnfErr File not found 


ioErr I/O error 

nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION PBRstFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _RstFilLock 

Parameter block 
--> 12 ioCompletion pointer 
<2 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 


--> 26 ioFVersNum byte 


PBRstFLock unlocks the file having the name pointed to by ioNamePtr (and on flat 
volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. 
Access paths currently in use aren't affected. 


Result codes noErr No error 
extFSErr External file system 
fnfErr File not found 


ioErr I/O error 

nsvErr No such volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


FUNCTION PBHRstFLock (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _HRstFLock 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 48 ioDirID long word 


PBHRstFLock is identical to PBRstFLock except that it accepts a directory ID in 
ioDirID. 


Result codes noErr No error 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
vLckdErr Software volume lock 
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wPrErr Hardware volume lock 


FUNCTION PBSetFVers (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _SetFilType 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 26 ioVersNum byte 
--> 28 ioMisc byte 


PBSetFVers has no effect on hierarchical volumes. On flat volumes, PBSetFVers 
changes the version number of the file having the name pointed to by ioNamePtr 
and version number ioVersNum, on the volume specified by ioVRefNum, to the 
version number stored in the high-order byte of ioMisc. Access paths currently 
in use aren't affected. 


Result codes noErr No error 
bdNamErr Bad file name 
dupFNErr Duplicate file name and version 
extFSErr External file system 
flLckdErr File locked 
fnfErr File not found 
nsvErr No such volume 
ioErr I/O error 
paramErr No default volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lock 


wrgVolTypErr Attempt to perform hierarchical operation 
on a flat volume 


FUNCTION PBRename (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _Rename 


Parameter block 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
aS 26 ioVersNum byte 
--> 28 ioMisc pointer 


Given a pointer to a file name in ioNamePtr (and on flat volumes, a version 
number in ioVersNum), PBRename changes the name of the file to the name pointed 
to by ioMisc. (If the name pointed to by ioNamePtr contains one or more colons, 
so must the name pointed to by ioMisc.) Access paths currently in use aren't 
affected. Given a pointer to a volume name in ioNamePtr or a volume reference 
number in ioVRefNum, it changes the name of the volume to the name pointed to by 
ioMisc. If a volume to be renamed is specified by its volume reference number, 
ioNamePtr can be NIL. 


Warning: If a volume to be renamed is specified by its volume name, be 
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sure that it ends with a colon, or Rename will consider it a 
file name. 


Result codes 


noErr 
bdNamErr 
dirFulErr 
dupFNErr 
extFSErr 
flckdErr 
fnfErr 
fsRnErr 
ioErr 
nsvErr 
paramErr 
vLckdErr 
wPrErr 


No error 

Bad file name 

File directory full 
Duplicate file name and version 
External file system 
File locked 

File not found 
Problem during rename 
I/O error 

No such volume 

No default volume 
Software volume lock 
Hardware volume lock 


FUNCTION PBHRename (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


_HRename 


ioCompletion 
ioResult 
ioNamePtr 
ioVRefNum 
ioMisc 


Trap macro 
Parameter block 

--> 12 

<-- 16 

--> 18 

--> 22 

--> 28 

--> 48 


ioDirID 


pointer 
word 
pointer 
word 
pointer 
long word 


PBHRename is identical to PBRename except that it accepts a directory ID in 
ioDirID and can be used to rename directories as well as files and volumes. 
Given a pointer to the name of a file or directory in ioNamePtr, PBHRename 
changes it to the name pointed to by ioMisc. Given a pointer to a volume name in 
ioNamePtr or a volume reference number in ioVRefNum, it changes the name of the 
volume to the name pointed to by ioMisc. 


Warning: PBHRename cannot be used to change the directory a file is in. 


Result codes 


noErr 
bdNamErr 
dirFulErr 
dirNFErr 
dupFNErr 
extFSErr 
flckdErr 
fnfErr 
fsRnErr 
ioErr 
nsvErr 
paramErr 
vLckdErr 
wPrErr 


No error 

Bad file name 

File directory full 

Directory not found or incomplete pathname 
Duplicate file name and version 
External file system 

File locked 

File not found 

Problem during rename 

I/O error 

No such volume 

No default volume 

Software volume lock 

Hardware volume lock 


Hierarchical Directory Routines 


Warning: The routines described in this section operate only with the 
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hierarchical version of the File Manager; if used on a Macintosh 
equipped only with the 64K ROM version of the File Manager, 
they will generate a system error. 

FUNCTION PBGetCatInfo(paramBlock: CInfoPBPtr; aSync: BOOLEAN): OSErr; 


e*eClick on the X-Ref button, and refer to Technical Note #69.¢e« 


Trap macro _GetCatiInfo 

Parameter block 
Files: Directories: 
--> 12 ioCompletion pointer --> 12 ioCompletion pointer 
<-- 16 ioResult word <-- 16 ioResult word 
<-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer 
--> 22 ioVRefNum word --> 22 ioVRefNum word 
<-- 24 ioFRefNum word <-- 24 ioFRefNum word 
--> 28 ioFDirIndex word --> 28 ioFDirIndex word 
<-- 30 ioFlAttrib byte <-- 30 ioFlAttrib byte 
<-- 31 ioACUser byte access rights for directory only 
<-- 32 ioFlFndrinfo 16 bytes <-- 32 ioDrUsrWds 16 bytes 
<-> 48 ioDirID long word <-> 48 ioDrDirID long word 
<-- 52 ioFlStBlk word <-- 52 ioDrNmFls word 
<-- 54 ioFlLgLen long word 
<-- 58 ioFlPyLen long word 
<-- 62 ioFLRStBLk word 
<-- 64 ioFlRLgLen long word 
<-- 68 ioFlLRPyLen long word 
<-- 72 ioFlCrDat long word <-- 72 ioDrCrDat long word 
<-- 76 LoFlMdDat long word <-- 76 ioDrMdDat long word 
<-- 80 ioFlBkDat long word <-- 80 ioDrBkDat long word 
<-- 84 ioFlXFndriInfo 16 bytes <-- 84 ioDrFndriInfo 16 bytes 
<-- 100 ioFlParID long word <-- 100 ioDrParID long word 
<-- 104 =ioFlClpSiz long word 


PBGetCatInfo gets information about the files and directories in a file catalog. 
To determine whether the information is for a file or a directory, test bit 4 of 
ioFlAttrib, as described in the section "CInfoPBRec". The information that's 
returned for files is shown in the left column, and the corresponding 
information for directories is shown in the right column. 


If ioFDirIndex is positive, the File Manager returns information about the file 
or directory whose directory index is ioFDirIndex in the directory specified by 
ioVRefNum (this will be the root directory if a volume reference number is 
provided). 


If ioFDirIndex is 0, the File Manager returns information about the file or 
directory specified by ioNamePtr, in the directory specified by ioVRefNum 
(again, this will be the root directory if a volume reference number is 
provided). 


If ioFDirIndex is negative, the File Manager ignores ioNamePtr and returns 
information about the directory specified by ioDirID. 


With files, PBGetCatInfo is similar to PBHGetFileInfo but returns some 
additional information. If the file is open, the reference number of the first 
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access path found is returned in ioFRefNum, and the name of the file is returned 
in ioNamePtr (unless ioNamePtr is NIL). 


For server volume directories, in addition to the normal return parameters the 
ioACUser field returns the user's access rights in the following format: 


Bit 7 if set, user is not the owner of the directory. 
if clear, user is the owner of the directory. 
6-3 Reserved; this is returned set to zero. 
2 If set, user does not have Make Changes privileges 
to the directory. 
If clear, user has Make Changes privileges to the directory. 


1 If set, user does not have See Files privileges to the directory. 
If clear, user has See Files privileges to the directory. 
0 If set, user does not have See Folders privileges 


to the directory. 
If clear, user has See Folders privileges to the directory. 


For example, if ioACUser returns zero for a given server volume directory, you 
know that the user is the owner of the directory and has complete privileges to 
it. 


Result codes noErr No error 
bdNamErr Bad file name 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION PBSetCatInfo (paramBlock: CInfoPBPtr; async: BOOLEAN) : OSErr; 
Trap macro _SetCatiInfo 


Parameter block 


Files: Directories: 

--> 12 ioCompletion pointer --> 12 ioCompletion pointer 
<- 5 16 ioResult word <-- 16 ioResult word 

<-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer 
--> 22 ioVRefNum word --> 22 ioVRefNum word 

--> 30 ioFlAttrib byte --> 30 ioFlAttrib byte 

--> 32 ioFlFndrinfo 16 bytes --> 32 ioDrUsrWds 16 bytes 
--> 48 ioDirID long word --> 48 ioDrDirID long word 
--> 72 ioFlCrDat long word --> 72 ioDrCrDat long word 
--> 76 ioFlLMdDat long word --> 76 ioDrMdDat long word 
--> 80 ioFlBkDat long word --> 80 ioDrBkDat long word 
--> 84 ioFlXFndrinfo 16 bytes --> 84 ioDrFndrinfo 16 bytes 


--> 104 =ioFlClpSiz long word 


PBSetCatInfo sets information about the files and directories in a catalog. With 
files, it's similar to PBHSetFileInfo but lets you set some additional 
information. The information that can be set for files is shown in the left 
column, and the corresponding information for directories is shown in the right 
column. 
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Result codes noErr No error 
bdNamErr Bad file name 
dirNFErr Directory not found or incomplete pathname 
extFSErr External file system 
fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 
paramErr No default volume 


FUNCTION PBCatMove (paramBlock: CMovePBPtr; async: BOOLEAN) : OSErr; 


e*eClick on the X-Ref button, and refer to Technical Note #226. eee 


Trap macro _CatMove 

Parameter block 
--> 12 ioCompletion pointer 
<2 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 28 ioNewName pointer 
--> 36 ioNewDirID long word 
--> 48 ioDirID long word 


PBCatMove moves files or directories from one directory to another. The name of 
the file or directory to be moved is pointed to by ioNamePtr; ioVRefNum contains 
either the volume reference number or working directory reference number. A 
directory ID can be specified in ioDirID. The name and directory ID of the 
directory to which the file or directory is to be moved are specified by 
ioNewName and ioNewDirID. 


PBCatMove is strictly a file catalog operation; it does not actually change the 
location of the file or directory on the disk. PBCatMove cannot move a file or 
directory to another volume (that is, ioVRefNum is used in specifying both the 
source and the destination). It also cannot be used to rename files or 
directories; for that, use PBHRename. 


Result codes noErr No error 
badMovErr Attempt to move into offspring 
bdNamErr Bad file name or attempt to move into a file 
dupFNErr Duplicate file name and version 


fnfErr File not found 
ioErr I/O error 
nsvErr No such volume 


paramErr No default volume 
vLckdErr Software volume lock 
wPrErr Hardware volume lockWorking Directory Routines 


Warning: The routines described in this section operate only with the 
hierarchical version of the File Manager; if used on a Macintosh 
equipped only with the 64K ROM version of the File Manager, they 
will generate a system error. 


FUNCTION PBOpenWD (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 
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Trap macro _OpenwD 


Parameter block 


--> 12 ioCompletion pointer 
<: 5 16 ioResult word 

--> 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 

--> 28 ioWDProcID long word 
--> 48 iowDDirID long word 


PBOpenwWD takes the directory specified by ioVRefNum, ioWDDirID, and ioWDProcID 
and makes it a working directory. (You can also specify the directory using a 
combination of partial pathname and directory ID.) It returns a working 
directory reference number in ioVRefNum that can be used in subsequent calls. 


If a given directory has already been made a working directory using the same 
iowWDProcID, no new working directory will be opened; instead, the existing 
working directory reference number will be returned. If a given directory was 
already made a working directory using a different ioWDProcID, a new working 
directory reference number is returned. 


Result codes noErr No error 
tmwdoErr Too many working directories open 


FUNCTION PBCloseWD (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 


Trap macro _CloseWD 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 22 ioVRefNum word 


PBCloseWD releases the working directory whose working directory reference 
number is specified in ioVRefNum. 


Note: If a volume reference number is specified in ioVRefNum, PBCloseWD 
does nothing. 


Result codes noErr No error 
nsvErr No such volume 


FUNCTION PBGetWDInfo (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 


Trap macro _GetWDInfo 

Parameter block 
--> 12 ioCompletion pointer 
€-- 16 ioResult word 
<-- 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
--> 26 iowDIndex word 


<-> 28 iowDProcID long word 
<-> 32 iowDVRefNum = _-word 
<-- 48 iowWDDirID long word 
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PBGetWDInfo returns information about the specified working directory. The 
working directory can be specified either by its working directory reference 
number in ioVRefNum (in which case ioWDIndex should be 0), or by its index 
number in ioWDIndex. In the latter case, if ioVRefNum is nonzero, it's 
interpreted as a volume specification (volume reference number or drive number), 
and only working directories on that volume are indexed. 


IOWDVRefNum always returns the volume reference number. IOVRefNum returns a 
working directory reference number when a working directory reference number is 
passed in that field; otherwise, it returns a volume reference number. The 
volume name is returned in ioNamePtr. 


If IOWDProcID is nonzero, only working directories with that identifier are 
indexed; otherwise all working directories are indexed. 


Result codes noErr No error 
nsvErr No such volume 


Shared Volume HFS Routines 


FUNCTION PBHGetVolParms (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _GetVolParms 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long volume name specifier 
--> 22 ioVRefNum word volume refNum 
<-- 32 ioBuffer long ptr to vol parms data 
--> 36 ioReqCount long size of buffer area 
<-- 40 ioActCount long length of vol parms data 


The PBHGetVolParms call is used to return volume level information. ioVRefNum 
or ioFileName contain the volume identifier information. ioReqCount and 
ioBuffer contain the size and location of the buffer in which to place the 
volume parameters. The actual size of the information is returned in 
ioActCount. 


The format of the buffer is described below. Version 01 of the buffer is shown 
below along with offsets into the buffer and their equates: 


offset 0 vMVersion word version number (currently 01) 
2 vMAttrib long attributes (detailed below) 
6 vMLocalHand~ long handle used to keep information 
necessary for shared volumes 
10 vMServerAdr long AppleTalk server address (zero if 


not supported) 


On creation of the VCB (right after mounting), vMLocalHand will be a handle to a 
2 byte block of memory. The Finder uses this for its local window list storage, 
allocating and deallocating memory as needed. It is disposed of when the volume 
is unmounted. 
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For AppleTalk server volumes, vMServerAdr contains the AppleTalk internet 


address of 
server. 


vMAttrib contains attributes information (32 flag bits) about the volume. 


the server. 


This can be used to tell which volumes are for which 


These 


bits and their equates are defined as follows: 


bit 31 bLimitFCBs If set, Finder limits the number of FCBs used 
during copies to 8 (instead of 16). 

30 bLocalWList If set, Finder uses the returned shared volume 
handle for its local window list. 

29 bNoMiniFndr If set, Mini Finder menu item is disabled. 

28 bNoVNEdit If set, volume name cannot be edited. 

27 bNoLclSync If set, volume's modification date is not set by 
any Finder action. 

26 bTrshOffLine If set, anytime volume goes offline, it is zoomed 
to the Trash and unmounted. 

25 bNoSwitchTo If set, Finder will not switch launch to any 
application on the volume. 

24-21 Reserved-server volumes should return these 
bits set, all other disks should return these 
bits cleared. 

20 bNoDeskItems If set, no items may be placed on the Finder desktop. 

19 bNoBootBlks If set, no boot blocks on this volume—not a startup 
volume. SetStartup menu item will be disabled; 
bootblocks will not be copied during copy operations. 

18 bAccessCntl If set, volume supports AppleTalk AFP access control 
interfaces. The calls GetLoginIinfo, GetDirAccess, 
SetDirAccess, MapID, and MapName are supported. 
Special folder icons are used. Access Privileges 
menu item is enabled for disk and folder items. The 
privileges field of GetCatInfo calls are assumed to 
be valid. 

17. bNoSysDir If set, volume doesn't support a system directory; 
no switch launch to this volume. 

16 bEXxtFSVol If set, this volume is an external file system 
volume. Disk init package will not be called. 
Erase Disk menu item is disabled. 

15 bHasOpenDeny If set, supports OpenDeny and OpenRFDeny calls. 
For copy operations, source files are opened with 
enable read/deny write and destination files are 
opened enable write/deny read and write. 

14 bHasCopyFile If set, CopyFile call supported. CopyFile is 
used in copy and duplicate operations if both source 
and destination volumes have same server address. 

13. bHasMoveRename If set, MoveRename call supported. 

12 bHasNewDesk If set, all of the new desktop calls are supported 
(for example, OpenDB, AddIcon, AddComment) . 

11-0 Reserved—these bits should be returned cleared. 
FUNCTION PBHGetLogInInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _GetLogInInfo 
Parameter block 

--> 12 ioCompletion long optional completion routine ptr 
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<-- 16 ioResult word error result code 


--> 22 ioVRefNum word volume refNum 
<-- 26 ioObjType word log in method 
<-- 28 ioObjNamePtr long ptr to log in name buffer 


PBHGetLogInInfo returns the method used for log-in and the user name specified 
at log-in time for the volume. The log-in user name is returned as a Pascal 
string in ioObjNamePtr. The maximum size of the user name is 31 characters. 
The log-in method type is returned in ioObjType. 


FUNCTION PBHGetDirAccess (paramBlock: HParmBlkPtr; async: BOOLEAN): OSErr; 


Trap macro _GetDirAccess 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long directory name 
--> 22 ioVRefNum word volume refNum 
<-- 36 ioACOwnerID — long owner ID 
<-- 40 ioACGroupID long group ID 
<-- 44 ioACAccess long access rights 
--> 48 ioDirID long directory ID 


PBHGetDirAccess returns access control information for the folder pointed to by 
the ioDirID/ioFIleName pair. ioACOwnerID will return the ID for the folder's 
owner. ioACGroupID will return the ID for the folder's primary group. The 
access rights are returned in ioACAccess. 


A fnfErr is returned if the pathname does not point to a valid directory. An 
AccessDenied error is returned if the user does not have the correct access 
rights to examine this directory. 


FUNCTION PBHSetDirAccess (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _SetDirAccess 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long pathname identifier 
--> 22 ioVRefNum word volume refNum 


--> 36 ioACOwnerID long owner ID 
--> 40 ioACGroupID — long group ID 
--> 44 ioACAccess long access rights 
--> 48 ioDirID long directory ID 


PBHSetDirAccess allows you to change the access rights to a folder pointed to by 
the ioFileName/ioDirID pair. I0ACOwnerID contains the new owner ID. 

IOACGroupID contains the group ID. IOACAccess contains the folder's access 
rights. You cannot set the owner bit or the user's rights of the directory. To 
change the owner or group, you should set the ioACOwnerID or ioACGroupID field 
with the appropriate ID of the new owner/group. You must be the owner of the 
directory to change the owner or group ID. 
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A fnfErr is returned if the pathname does not point to a valid directory. An 
AccessDenied error is returned if you do not have the correct access rights to 
modify the parameters for this directory. A paramErr is returned if you try to 
set the owner bit or user's rights bits. 


FUNCTION PBHMapID (paramBlock: HParmBlkPtr; async: BOOLEAN): OSErr; 


Trap macro _MapID 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long pathname identifier 
--> 22 ioVRefNum word volume refNum 
--> 26 io0bjType word function code 
<-- 28 ioObjNamePtr long ptr to retrnd creator/group name 
--> 32 io0bjID long creator/group ID 


PBHMapID returns the name of a user or group given its unique ID. IOObjID 
contains the ID to be mapped. The value zero for ioObjID is special cased and 
will always return a NIL name. AppleShare uses this to signify <Any User>. 
I00bjType is the mapping function code; it's 1 if you're mapping an owner ID to 
owner name or 2 if you're mapping a group ID to a group name. The name is 
returned as a Pascal string in ioObjNamePtr. The maximum size of the name is 31 
characters. 


A fnfErr is returned if an unrecognizable owner or group ID is passed. 


FUNCTION PBHMapName(paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _MapName 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long volume identifier (may be NIL) 
--> 22 ioVRefNum word volume refNum 
--> 28 io0bjNamePtr long owner or group name 
--> 26 io0bjType word function code 
<-- 32 io0bjID long creator/group ID 


PBHMapName returns the unique user ID or group ID given its name. The name is 
passed as a string in ioObjNamePtr. If a NIL name is passed, the ID returned 
will always be zero. The maximum size of the name is 31 characters. I00bjType 
is the mapping function code; it's 3 if you're mapping an owner name to owner ID 
or 4 if you're mapping a group name to a group ID. I00bjID will contain the 
mapped ID. 


A fnfErr is returned if an unrecognizable owner or group name is passed. 
FUNCTION PBHCopyFile (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _CopyFile 


Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
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<-- 16 ioResult word error result code 


--> 18 ioFileName long ptr to source pathname 

--> 22 ioVRefNum word source vol identifier 

--> 24 ioDstVRefNum word destination vol identifier 

--> 28 ioNewName long ptr to destination pathname 

--> 32 ioCopyName long ptr to optional name (may be NIL) 
--> 36 ioNewDirID long destination directory ID 

--> 48 ioDirID long source directory ID 


PBHCopyFile duplicates a file on the volume and optionally renames it. It is an 
optional call for AppleShare file servers. You should examine the returned flag 
information in the PBHGetVolParms call to see if this volume supports CopyFile. 


For AppleShare file servers, the source and destination pathnames must indicate 
the same file server; however, it may point to a different volume for that file 
server. A useful way to tell if two file server volumes are on the same file 
server is to make the GetVolParms call and compare the server addresses 
returned. The server will open source files with read/deny write enabled and 
destination files with write/deny read and write enabled. 


IOVRefNum contains a source volume identifier. The source pathname is 
determined by the ioFileName/ioDirID pair. IODstVRefNum contains a destination 
volume identifier. AppleShare 1.0 required that it be an actual volume 
reference number; however, on future versions it can be a WDRefNum. The 
destination pathname is determined by the ioNewName/ioNewDirID pair. I0CopyName 
may contain an optional string used in renaming the file. If it is non-NIL then 
the file copy will be renamed to the specified name in ioCopyName. 


A fnfErr is returned if the source pathname does not point to an existing file 
or the destination pathname does not point to an existing directory. An 
AccessDenied error is returned if the user does not have the right to read the 
source or write to the destination. A dupFnErr is returned if the destination 
already exists. A DenyConflict error is returned if either the source or 
destination file could not be opened under the access modes described above. 


FUNCTION PBHMoveRename (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
Trap macro _MoveRename 


Parameter block 


--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 

--> 18 ioFileName long ptr to source pathname 

--> 22 ioVRefNum word source vol identifier 

--> 28 ioNewName long ptr to destination pathname 

--> 32 ioBuffer long ptr to optional name (may be NIL) 
--> 36 ioNewDirID long destination directory ID 

--> 48 ioDirID long source directory ID 


PBHMoveRename allows you to move (not copy) an item and optionally to rename it. 
The source and destination pathnames must point to the same file server volume. 


IOVRefNum contains a source volume identifier. The source pathname is specified 
by the ioFileName/ioDirID pair. The destination pathname is specified by the 
ioNewName/ioNewDirID pair. IOBuffer may contain an optional string used in 
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renaming the item. If it is non-NIL then the moved object will be renamed to 
the specified name in ioBuffer. 


A fnfErr is returned if the source pathname does not point to an existing 
object. An AccessDenied error is returned if the user does not have the right 
to move the object. A dupFnErr is returned if the destination already exists. 
A badMovErr is returned if an attempt is made to move a directory into one of 
its descendent directories. 


FUNCTION PBHOpenDeny (paramBlock: HParmBlkPtr; async: BOOLEAN): OSErr; 


Trap macro _OpenDeny 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long ptr to pathname 
aS 22 ioVRefNum word vol identifier 
<-- 24 ioRefNum word file refNum 
--> 26 ioDenyModes word access rights data 
--> 48 ioDirID long directory ID 


PBHOpenDeny opens a file's data fork under specific access rights. It creates 
an access path to the file having the name pointed to by ioFileName/ioDirID. 
The path reference number is returned in ioRefNum. 


IODenyModes contains a word of access rights information. The format for these 
access rights is: 


bits 15-6 Reserved—should be cleared. 
If set, other writers are denied access. 
If set, other readers are denied access. 
—2 Reserved—should be cleared. 
If set, write permission requested. 
If set, read permission requested. 


OrWhU 


A fnfErr is returned if the input specification does not point to an existing 
file. <A permErr is returned if the file is already open and you cannot open it 
under the deny modes that you have specified. An opWrErr is returned if you 
have asked for write permission and the file is already opened by you for write. 
The already opened path reference number is returned in ioRefNum. An 
AccessDenied error is returned if you do not have the right to access the file. 


FUNCTION PBHOpenRFDeny (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _OpenRFDeny 
Parameter block 
--> 12 ioCompletion long optional completion routine ptr 
<-- 16 ioResult word error result code 
--> 18 ioFileName long ptr to pathname 
--> 22 ioVRefNum word vol identifier 
<-- 24 ioRefNum word file refNum 
--> 26 ioDenyModes __ word access rights data 
--> 48 ioDirID long directory ID 
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PBHOpenRFDeny opens a file's resource fork under specific access rights. 

It creates an access path to the file having the name pointed to by 
ioFileName/ioDirID. The path reference number is returned in ioRefNum. The 
format of the access rights data contained in ioDenyModes is described under the 
OpenDeny call. 


A fnfErr is returned if the input specification does not point to an existing 
file. A permErr is returned if the file is already open and you cannot open it 
under the deny modes that you have specified. An opWrErr is returned if you 
have asked for write permission and the file is already opened by you for write. 
The already-opened path reference number is returned in ioRefNum. An 
AccessDenied error is returned if you do not have the right to access the file. 
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DATA ORGANIZATION ON VOLUMES 


This section explains how information is organized on volumes. Most of the 
information is accessible only through assembly language, but may be of interest 
to some advanced Pascal programmers. 


The File Manager communicates with device drivers that read and write data via 
block-level requests to devices containing Macintosh-initialized volumes. 
(Macintosh-initialized volumes are volumes initialized by the Disk 
Initialization Package.) The actual type of volume and device is unimportant to 
the File Manager; the only requirements are that the volume was initialized by 
the Disk Initialization Package and that the device driver is able to 
communicate via block-level requests. 


The 3 1/2-inch built-in and optional external drives are accessed via the Disk 
Driver. The Hard Disk 20 is accessed via the Hard Disk 20 Driver. If you want to 
use the File Manager to access files on Macintosh-initialized volumes on other 
types of devices, you must write a device driver that can read and write data 
via block-level requests to the device on which the volume will be mounted. If 
you want to access files on volumes not initialized by the Macintosh, you must 
write your own external file system (see the section "Using an External File 
System"). 


The information on all block-formatted volumes is organized in logical blocks 
and allocation blocks. Logical blocks contain a number of bytes of standard 
information (512 bytes on Macintosh-initialized volumes), and an additional 
number of bytes of information specific to the device driver (12 bytes on 
Macintosh-initialized volumes; for details, see the Disk Driver chapter). 
Allocation blocks are composed of any integral number of logical blocks, and are 
simply a means of grouping logical blocks together in more convenient parcels. 
The allocation block size is a volume parameter whose value is set when the 
volume is initialized; it cannot be changed unless the volume is reinitialized. 


The remainder of this section applies only to Macintosh-initialized volumes; the 
information may be different in future versions of Macintosh system software. 
There are two types of Macintosh-initialized volumes—flat directory volumes and 
hierarchical directory volumes. Other volumes must be accessed via an external 
file system, and the information on them must be organized by an external 
initializing program. 


Flat Directory Volumes 


A flat directory volume contains system startup information in logical blocks 0 
and 1 (see Figure 12) that's read in at system startup. This information 
consists of certain configurable system parameters, such as the capacity of the 
event queue, the initial size of the system heap, and the number of open files 
allowed. The development system you're using may include a utility program for 
modifying the system startup blocks on a volume. 
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Logical block 2 of the volume begins the master directory block. The master 
directory block contains volume information and the volume allocation block map, 
which records whether each block on the volume is unused or what part of a file 
it contains data from. 


lovical block 0 
system startup 
information 
logical block 1 
zero if nota startup disk 


eee 


block map master directory block 
logical black 3 


mage 


logical block 4 
file directory 


logical block n 
logical block n + 1 allocation block 2 
Tile contents 
logical block ?O9 allocation black m 
Figure 12-A 400K Yolume With 1K Allocation Blocks 
Figure 12—A 400K Volume With 1K Allocation Blocks 


The master directory "block" always occupies two blocks—the Disk Initialization 
Package varies the allocation block size as necessary to achieve this 
constraint. 


The file directory begins in the next logical block following the block map; it 
contains descriptions and locations of all the files on the volume. The rest of 
the logical blocks on the volume contain files or garbage (such as parts of 
deleted files). The exact format of the volume information, volume allocation 
block map, and file directory is explained in the following sections. 


Volume Information 
The volume information is contained in the first 64 bytes of the master 


directory block (see Figure 13). This information is written on the volume when 
it's initialized, and modified thereafter by the File Manager. 
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date and tine of initialization 

date and the of last modification 
number of files in divectory 

first block of directory 

length of directory in blocks 
mumber of allocation blocks 
allocation block size 

number of bytes to allocate 

first allocation block in block map 
next unused file number 

moumber of unused allocation blocks 


arv¥M + 1 (hevtes) chavacters of volume name 


Figure 13-Yolume [nformation on Flat Directory Yolumes 


Figure 13—Volume Information on Flat Directory Volumes 


DrAtrb contains the volume attributes, as follows: 


Bit Meaning 
7 Set if volume is locked by hardware 
15 Set if volume is locked by software 


DrClpSiz contains the minimum number of bytes to allocate each time the Allocate 
function is called, to minimize fragmentation of files; it's always a multiple 
of the allocation block size. DrNxtFNum contains the next unused file number 
(see the "File Directory" section below for an explanation of file numbers). 


Volume Allocation Block Map 
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The volume allocation block map represents every allocation block on the volume 
with a 12-bit entry indicating whether the block is unused or allocated to a 
file. It begins in the master directory block at the byte following the volume 
information, and continues for as many logical blocks as needed. 


The first entry in the block map is for block number 2; the block map doesn't 
contain entries for the system startup blocks. Each entry specifies whether the 
block is unused, whether it's the last block in the file, or which allocation 
block is next in the file: 


Entry Meaning 

0 Block is unused 

1 Block is the last block of the file 
2-—4095 Number of next block in the file 


For instance, assume that there's one file on the volume, stored in allocation 
blocks 8, 11, 12, and 17; the first 16 entries of the block map would read 


0000001100121700001 


The first allocation block on a volume typically follows the file directory. 
It's numbered 2 because of the special meaning of numbers 0 and 1. 


Note: As explained below, it's possible to begin the allocation blocks 
immediately following the master directory block and place the file 
directory somewhere within the allocation blocks. In this case, the 
allocation blocks occupied by the file directory must be marked with 
$FFF's in the allocation block map. 


Flat File Directory 


The file directory contains an entry for each file. Each entry lists information 
about one file on the volume, including its name and location. Each file is 
listed by its own unique file number, which the File Manager uses to distinguish 
it from other files on the volume. 


A file directory entry contains 51 bytes plus one byte for each character in the 
file name. If the file names average 20 characters, a directory can hold seven 
file entries per logical block. Entries are always an integral number of words 
and don't cross logical block boundaries. The length of a file directory depends 
on the maximum number of files the volume can contain; for example, on a 400K 
volume the file directory occupies 12 logical blocks. 


The file directory conventionally follows the block map and precedes the 
allocation blocks, but a volume-initializing program could actually place the 
file directory anywhere within the allocation blocks as long as the blocks 
occupied by the file directory are marked with $FFF's in the block map. 


The format of a file directory entry is shown in Figure 14. 
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bit? = 1 if entoy used; bitO = 1 if file locked 
information used by the Finder 

first allocation block of data fork 

logical end-of-file of data fork 

plovsical end-of-file of data fork 

first allocation block of resource fork 

logical end-of-file of resource fork 

phlreysical end-of-file of resource fork 

date and thine of creation 

date and time of last modification 


Figure 14-A File Directory Entry 


Figure 14-A File Directory Entry 


FLStBLk and flRStBlk are 0 if the data or resource fork doesn't exist. FlCrDat 
and flMdDat are given in seconds since midnight, January 1, 1904. 


Each time a new file is created, an entry for the new file is placed in the file 
directory. Each time a file is deleted, its entry in the file directory is 
cleared, and all blocks used by that file on the volume are released. 


Hierarchical Directory Volumes 


A hierarchical directory volume contains system startup information in logical 
blocks 0 and 1 (see Figure 15) that's read in at system startup. This 
information is similar to the system startup information for flat directory 
volumes; it consists of certain configurable system parameters, such as the 
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capacity of the event queue, the initial size of the system heap, and the number 
of open files allowed. 


lovical block 0 
System startip 
infomation zero if nota startup disk 
lovical block 1 


logical block 3 
Folume bit map 


logical block n 

logical block n + 1 allocation block 2 
file contents 

logical block 1599 allocation block mm 


Figure 15-An 800F Yolume With 1E. Allocation Blocks 


Figure 15-An 800K Volume With 1K Allocation Blocks 


Logical block 2 of the volume (also known as the volume information block) 
contains the volume information. This volume information is a superset of the 
volume information found on flat directory volumes. Logical block 3 of the 
volume begins the volume bit map, which records whether each block on the volume 
is used or unused. The rest of the logical blocks on the volume contain files or 
garbage (such as parts of deleted files). 


The volume bit map on hierarchical directory volumes replaces the volume 
allocation block map used on flat directory volumes. While the bit map does 
handle volume space management (as does the block map), it does not handle file 
mapping. A separate file, known as the extents tree file, performs this 
function. Finally, a file known as the catalog tree file is responsible for 
maintaining the hierarchical directory structure; it corresponds in function to 
the file directory found on flat directory volumes. 


The exact format of the volume information, volume bit map, extents tree file, 
and catalog tree file is explained in the following sections. The discussion of 
the extents tree and catalog tree files is preceded by a short introduction to a 
data structure known as a B*-tree that's used to organize and access the 
information in these files.Volume Information 
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The volume information is contained in the first 104 bytes of the volume 
information block (see Figure 16). This information is written on the volume 
when it's initialized, and modified thereafter by the File Manager. 


byte 0 always $4244 
2 date and time of initialization 
6 date and time of last modification 
r volume atubute 
12 number of files in directory 
14 first block of volume bit map 
16 used internally 
18 number of allocation blocks 
20 allocation block size 
24 default clump size 
28 first block in bit map 
30 next unused directory ID or file number 
34 number of unugzed allocation blocks 
36 jngth of volume name 
a7 characters of volume name 
64 date and time of last abackup 
e8 vse tena 
70 volume wate count 
74 clump size of extents tee file 
vo clump size of catalog tree file 
BZ number of directories in root 
rT number of files on volume 
rata number of directories on volume 
92 information used by the Finder 
124 used internally 
126 nsed internally 
12 nied inert 
130 length of extents tee (LEOF and PEOF) 
134 extent record for extents tree 
146 length of catalog tee (LEOF and PEOF) 
150 first extent record for catalog tee 


Figure 16-Yolume [Information on Hierarchical Directory Yolumes 
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Figure 16—Volume Information on Hierarchical Directory Volumes 


64K ROM note: The volume information on a flat directory volume is a 
subset of the hierarchical volume information. The flat 
directory volume information contains only the fields up 
to and including drVN+1. In addition, the names of several 
fields have been changed in the hierarchical volume information 
to reflect their new function: drLsBkUp, drDirSt, drBlLn, 
and drNxtFNum have been changed to drLsMod, drVBMSt, drAllocPtr, 
and drNxtCNID respectively. All of the offsets of the flat 
directory volume information, however, have been preserved to 
maintain compatibility. 


DrLsMod contains the date and time that the volume was last modified (this is 
not necessarily when it was flushed). 


64K ROM note: DrLsMod replaces the field drLsBkUp from flat directory 
volumes. The name drLsBkUp was actually a misnomer; this 
field has always contained the date and time of the last 
modification, not the last backup. Another field, drVolBkUp, 
contains the date and time of the last backup. 


DrVBMSt replaces the field drDirSt; it contains the number of the first block in 
the volume bit map. 


DrAtrb contains the volume attributes, as follows: 


Bit Meaning 
7 Set if volume is locked by hardware 
15 Set if volume is locked by software 


DrClpSiz contains the default clump size for the volume. To promote file 
contiguity and avoid fragmentation, space is allocated to a file not in 
allocation blocks but in clumps. A clump is a group of contiguous allocation 
blocks. The clump size is always a multiple of the allocation block size; it's 
the minimum number of bytes to allocate each time the Allocate function is 
called or the end-of-file is reached during the Write routine. A clump size can 
be set when a particular file is opened, and can also be changed subsequently. 
If no clump size is specified, the value found in drClpSiz will be used. 


DrNxtCNID replaces the field drNxtFNum; it's either the next file number or the 
next directory ID to be assigned. 


Warning: The format of the volume information may be different in future 
versions of Macintosh system software. 


Volume Bit Map 


The flat directory file system uses the volume allocation block map to provide 
both volume space management and file mapping; the hierarchical file system 
instead uses a volume bit map. The block map contains a 12-bit entry for each 
allocation block. If an entry is 0, the corresponding allocation block is 
unused. If an allocation block is allocated to a file, its block map entry is 
nonzero, and can be used to find the next allocation block used by that file. 
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The File Manager keeps the entire block map in memory. The size of the block map 
is obviously a function of the number of allocation blocks on the volume. 
Similarly, the number of allocation blocks depends on the allocation block size. 
For larger volumes, the allocation block size must be increased in order to keep 
the block map to a reasonable size. 


A tradeoff occurs between waste of space and speed of file access in this 
Situation. Obviously, the use of large allocation blocks can waste disk space, 
particularly with small files. On the other hand, using smaller allocation 
blocks increases the size of the block map; this means the entire block map 
cannot be kept in memory at one time, resulting in a time-consuming sector- 
caching scheme. 


The hierarchical file system discards the block map concept entirely, and 
instead uses a structure known as the volume bit map. The bit map has one bit 
for each allocation block on the volume; if a particular block is in use, its 
bit is set. 


With extremely large volumes, the same space/time tradeoff can become an issue. 
In general, it's desirable to set the allocation block size such that the entire 
bit map can be kept in memory at all times. 


B*-Trees 


This section describes the B*-tree implementation used in the extents tree and 
catalog tree files. The data structures described in this section are accessible 
only through assembly language; an understanding of the B*-tree data structure 
is also assumed. 


The nodes of a B*-tree contain records; each record consists of certain 
information (either pointers or data) and a key associated with that information 
(see Figure 17). A basic feature of the B*-tree is that data is stored only in 
the leaf nodes. The internal nodes (also known as index nodes) contain pointers 
to other nodes; they provide an index, used in conjunction with a search key, 
for accessing the data records stored in the leaf nodes. 


kev dats ar pointer 


fup to 255 bytes) «| (limited only by size of node} 


Figure 17-A B*¥-Tree Hode Record 
Figure 17-A B*-Tree Node Record 


Within each node, the records are maintained so that their keys are in ascending 
order. Figure 18 shows a sample B*-tree; hypothetical keys have been inserted to 
illustrate the structure of the tree and the relationship between index and leaf 
nodes. 
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[a Footer] 1 Joiner 
[8 omer] 13 [pom] 


index nodes 


a 


[aati [eee | 


leaf modes 


Figure 18-A Sample B*¥-Tree 
Figure 18-A Sample B*-Tree 


When a data record is needed, the key of the desired record (the search key) is 
provided. The search begins at the root node (which is an index node, unless the 
tree has only one level), moving from one record to the next until the record 
with the highest key that's less than or equal to the search key is reached. The 
pointer of that record leads to another node, one level down in the tree. This 
process continues until a leaf node is reached; its records are examined until 
the desired key is found. (The desired key may not be found; in this case, the 
search stops when a key larger than the search key is reached.) Figure 19 shows 


a sample B*-tree search path; the arrows indicate the path to the second record 
in the second leaf node. 


[roe] 18 [poe 
[ Ypoter] 13 [pom 


index nodes 


ff 


[& [aes] 10] a | 


leaf nodes 


Figure 19-A Sample B*-Tree 
Figure 19-A Sample B*-Tree Search Path 


All nodes in the B*-tree are of the same fixed size; the structure of a node is 
shown in Figure 20. 
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offset to free space 
offset to record 1 
offset to record 0 


Figure 20-Structure of a B*¥-Tree Node 


node 
descriptor 


records 


record 
offsets 


Figure 2Q0-Structure of a B*-Tree Node 


Each node begins with the node descriptor. NDNRecs contains the number of 
records currently in the node. NDType indicates the type of node; it contains 
$FF if it's a leaf node and 0 if it's an index node. NDLevel indicates the level 
of the node in the tree; leaf nodes are always at level 1, the first level of 
index nodes above them are at level 2, and so on. 


NDBLink and ndFLink are used only with leaf nodes as a way of quickly moving 
through the data records; for each leaf node, they contain pointers to the 
previous and subsequent leaf nodes respectively. 


The records in a node can be of variable length; for this reason, offsets to the 
beginning of each record are needed. The records begin after the field ndNRecs; 
they're followed by the unused space. The offsets to the records begin at the 
end of the node and work backwards; they're followed by an offset to the unused 
space. 


Extents Tree File 


File mapping information (or the location of a file's data on the volume) is 
contained in the extents tree file. A file extent is a series of contiguous 
allocation blocks. Ideally, a file would be stored in a single extent. Except in 
the case of preallocated or small files, however, the contents of a particular 
file are usually stored in more than one extent on different parts of a given 
volume. The extents tree file, organized as a B*-tree, records the volume 
location and size of the various extents that comprise a file. 
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Each extent on a volume is identified by an extent descriptor; each descriptor 
consists of the number of the first allocation block of the extent followed by 
the length of the extent in blocks (see Figure 21). 


number of extent's first allocation block (word) 
number of allocation blocks in extent (word) 


Figure 21—-Extent Descriptor 
Figure 21—Extent Descriptor 


The extent descriptors are stored in extent records in the leaf nodes of the 
tree. Each extent record consists of a key followed by three extent descriptors. 
The extent records are kept sorted by the key, which has the format shown in 
Figure 22. 


be bey length in bye 
a $00 for data fork; $FF for resource fork 
2 uur 
6 allocation block number within file 


Figure 22-Extents Rey 
Figure 22-Extents Key 


Catalog Tree File 


The catalog tree file corresponds in function to the flat file directory found 
on volumes formatted by the 64K ROM. Whereas a flat file directory contains 
entries for files only, the catalog tree file contains three types of 
records—file records, directory records, and thread records. (Threads can be 
viewed as the branches connecting the nodes of a catalog tree.) The catalog tree 
file is organized as a B*-tree; all three types of records are stored in the 
leaf nodes. The index nodes contain the index records used to search through the 
tree. 


The catalog tree records consist of a key followed by the file, directory, or 
thread record. The records are kept sorted by key. The exact format of the key 
is shown in Figure 23. 


be bey lent in 3 
! wed intemal 
perent ID 
fie or direoory name 


Figure 23-Catalog Fey 
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Figure 23—Catalog Key 


A file record is a superset of the file directory entry found on volumes 
formatted by the 64K ROM; its contents are shown in Figure 24. 


bite 0 alwacvrs 2 for file records 
! vse internally 
2 bit ? = 1 if record used; bit O = 1 if file locked 
: a oe 
4 information used by the Finder 
20 ile number 
24 first allocation block of data fork 
26 logical end-of-file of data fork 
30 physical end-of-file of data fork 
34 first allocation block of resource fork 
36 logical end-of-file of resource fork 
40 physical end-of-file of resource fork 
Aq date and time of creation 
48 date and time of last modification 
52 date and time of last backup 
56 additional information used by the Finder 
72 file clump size 
74 first extent recond for data fork 
56 first extent record for resource fork 
98 used internally 


Figure 24-File Record 
Figure 24—File Record 


A directory record records information about a single directory; the format of a 
directory record is shown in Figure 25. 
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alwawvs 1 for directory records 
weed internally 

thes 

vale 

einewry ID 

date and time of creation 

date and time of last modification 
date and time of last backup 
information used by the Finder 
additional information used by the Finder 
ose internally 


Figure 25-Directory Record 


Figure 25—Directory Record 


Thread records are used in conjunction with directory records to provide a link 
between a given directory and its parent. For any given directory, the records 
describing all of its offspring are stored contiguously. A thread record 
precedes each set of offspring; it contains the directory ID and name of the 
parent and provides a path to the parent's directory record. The format of a 
thread record is shown in Figure 26. 


always 3 for thread records 
used intemelly 

used internally 

parent ID of associated directory 
name of associated directory 


Figure 26-Thread Record 
Figure 26—Thread Record 


A portion of a sample tree, along with the corresponding file, directory, and 
thread records, is shown in Figure 27. 
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<O>hMy¥al 
dit = 1 
parentlD = 0 
name = hy ol 
<1> FB 


dir = 35 
“121A 


parentID = 1 
narie = Mail 


<35> Bob 
<35> Jody 


Figure 27-Sample Tree, with Catalog Tree Records 


Figure 27-Sample Tree, with Catalog Tree Records 
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DATA STRUCTURES IN MEMORY 


This section describes the memory data structures used by the File Manager and 
any external file system that accesses files on Macintosh-initialized volumes. 
Some of this data is accessible only through assembly Language. 


The data structures in memory used by the File Manager and all external file 
systems include: 


e the file I/0 queue, listing all asynchronous routines awaiting 
execution (including the currently executing routine, if any) 

¢ the volume-control-block queue, listing information about each 
mounted volume 

* a copy of the volume bit map for each on-line volume (volume 

allocation block map for flat directory volumes) 

the file-control-block buffer, listing information about each access path 

volume buffers (one for each on-line volume) 

optional access path buffers (one for each access path) 

the drive queue, listing information about each drive connected 

to the Macintosh 


eoeee 


The File I/0 Queue 


The file I/O queue is a standard Operating System queue (described in the 
Operating System Utilities chapter) that contains parameter blocks for all 
asynchronous routines awaiting execution. Each time a routine is called, an 
entry is placed in the queue; each time a routine is completed, its entry is 
removed from the queue. 


Each entry in the file I/0 queue consists of a parameter block for the routine 
that was called. Most of the fields of this parameter block contain information 
needed by the specific File Manager routines; these fields are explained above 
in the section "Low-Level File Manager Routines". The first four fields of the 
parameter block, shown below, are used by the File Manager in processing the 
I/O requests in the queue. 


TYPE ParamBlockRec = RECORD 


qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 


ioCmdAddr: Ptr; {routine address} 
Poeercee {rest of block} 
END; 


QLink points to the next entry in the queue, and qlype indicates the queue type, 
which must always be ORD(ioQType). I0Trap and ioCmdAddr contain the trap word 
and address of the File Manager routine that was called. 


You can get a pointer to the header of the file I/0 queue by calling the File 
Manager function GetFSQHdr. 
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FUNCTION GetFSQHdr : QHdrPtr; [Not in ROM] 
GetFSQHdr returns a pointer to the header of the file I/0 queue. 


Assembly-language note: The global variable FSQHdr contains the 
header of the file I/0 queue. 


Volume Control Blocks 
eeeClick on the X-Ref button, and refer to Technical Note #106. eee 


Each time a volume is mounted, its volume information is read from it and is 
used to build a new volume control block in the volume-control-block queue 
(unless an ejected or off-line volume is being remounted). A copy of the volume 
block map is also read from the volume and placed in the system heap, and a 
volume buffer is created in the system heap. 


The volume-control-block queue is a standard Operating System queue that's 
maintained in the system heap. It contains a volume control block for each 
mounted volume. A volume control block is a 178-byte nonrelocatable block that 
contains volume-specific information. It has the following structure: 


TYPE VCB = RECORD 


qLink: QElemPtr; {next queue entry} 

qType: INTEGER; {queue type} 

vcbFlags: INTEGER; {bit 15=1 if dirty} 

vcbSigWord: INTEGER; {$4244 for hierarchical, $D2D7 for flat} 
vcbCrDate: LONGINT; {date and time of initialization} 
vcbLsMod: LONGINT; {date and time of last modification} 
vcbAtrb: INTEGER; {volume attributes} 

vcbNmF 1s: INTEGER; {number of files in directory} 
vcbVBMSt: INTEGER; {first block of volume bit map} 
vcbALlocPtr: INTEGER; {used internally} 

vcbNmALBLks: INTEGER; {number of allocation blocks} 
vcbALBLkSiz: LONGINT; {allocation block size} 

vcbClpSiz: LONGINT; {default clump size} 

vcbALBLSt: INTEGER; {first block in block map} 
VcbNxtCNID: LONGINT; {next unused directory ID or file number} 
vcbFreeBks: INTEGER; {number of unused allocation blocks} 
vcbVN: STRING[27]; {volume name} 

vcbDrvNum: INTEGER; {drive number} 

vcbDRefNum: INTEGER; {driver reference number} 

vcbFSID: INTEGER; {file-system identifier} 

vcbVRefNum: INTEGER; {volume reference number} 

vcbMAdr: Ptr; {pointer to block map} 

vcbBufAdr: Ptr; {pointer to volume buffer} 

vcbMLen: INTEGER; {number of bytes in block map} 
vcbDirIndex: INTEGER; {used internally} 

vcbDirBlLk: INTEGER; {used internally} 

vcbVolBkUp: LONGINT; {date and time of last backup} 
vcbVSeqNum: INTEGER; {used internally} 

vcbWrCnt: LONGINT; {volume write count} 

vcbXTClpSiz: LONGINT; {clump size of extents tree file} 
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vcbCTClpSiz: 
vcbNmRtDirs: 


vcbFilCnt: 
vcbDirCnt: 


vcbFndrinfo: 


vcbVCSize: 
vcbVBMCSiz: 
vcbCtlCSiz: 
vcbXTALBks: 
vcbCTALBks: 
vcbXTRef: 


vcbCTRef: 
vcbCtlBuf: 


vcbDirIDM: 
vcbOffsM: 


END; 


64K ROM note: 


LONGINT; 
INTEGER; 
LONGINT; 
LONGINT; 
ARRAY [1. 


INTEGER; 
INTEGER; 
INTEGER; 
INTEGER; 
INTEGER; 
INTEGER; 


INTEGER; 
Ptr; 


LONGINT; 
INTEGER 


{clump size of catalog tree file} 
{number of directories in root} 
{number of files on volume} 
{number of directories on volume} 


{used 
{used 
{used 
{size 
{size 
{path 


.8] OF LONGINT; {information used by } 


{ the Finder} 
internally} 
internally} 
internally} 
in blocks of extents tree file} 
in blocks of catalog tree file} 
reference number for extents } 


{ tree file} 


{path 


reference number for catalog } 


{ tree file} 

{pointer to extents and catalog } 
{ tree caches} 

{directory last searched} 
{offspring index at last search} 


A volume control block created for a flat volume is a subset 
of the above structure. It's actually smaller and contains 
only the fields up to and including vcbDirBlk. In addition, 
the names of several fields have been changed to reflect the 
fact that they contain different information on hierarchical 


volumes: 


vcbLsBkUp, vcbDirSt, vcbBlLn, vcbNmBlks, and 


vcbNxtFNum have been changed to vcbLsMod, vcbVBMSt, 
vcbAllocPtr, vcbNmALBlks, and vcbNxtCNID respectively. 


QLink points to the next entry in the queue, and qlype indicates the queue type, 
which must always be ORD(fsQType). Bit 15 of vcbFlags is set if the volume 
information has been changed by a routine call since the volume was last 
affected by a FlushVol call. 


VCBLsMod contains the date and time that the volume was last modified (this is 
not necessarily when it was flushed). 


64K ROM note: 


VCBLsMod replaces the field vcbLsBkUp from flat directory 
volumes. The name vcbLsBkUp was actually a misnomer; this 
field has always contained the date and time of the last 
modification, not the last backup. Another field, vcbVolBkUp, 
contains the date and time of the last backup. 


VCBAtrb contains the volume attributes, as follows: 


Bit Meaning 

0-4 Set if inconsistencies were found between the volume 
information and the file directory when the volume was mounted 

6 Set if volume is busy (one or more files are open) 

7 Set if volume is locked by hardware 

15 Set if volume is locked by software 


VCBVBMSt contains the number of the first block in the volume bit map; on flat 
volumes, it contains the first block of the file directory. VCBNmALBLks contains 
the number of allocation blocks on the volume, and vcbFreeBks specifies how many 
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of those blocks are unused. VCBALBLSt is used only with flat volumes; it 
contains the number of the first block in the block map. 


VCBDrvNum contains the drive number of the drive on which the volume is mounted; 
vcbDRefNum contains the driver reference number of the driver used to access the 
volume. When a mounted volume is placed off-line, vcbDrvNum is cleared. When a 
volume is ejected, vcbDrvNum is cleared and vcbDRefNum is set to the negative of 
vcbDrvNum (becoming a positive number). VCBFSID identifies the file system 
handling the volume; it's 0 for volumes handled by the File Manager, and nonzero 
for volumes handled by other file systems. 


When a volume is placed off-line, its buffer and bit map (or block map, in the 
case of flat directory volumes) are released. When a volume is unmounted, its 
volume control block is removed from the volume-control-block queue. 


You can get a pointer to the header of the volume-control-block queue by calling 
the File Manager function GetVCBQHdr. 


FUNCTION GetVCBQHdr : QHdrPtr; [Not in ROM] 
GetVCBQHdr returns a pointer to the header of the volume-control-block queue. 
Assembly-language note: The global variable VCBQHdr contains the header 

of the volume-control-block-queue. The default 


volume's volume control block is pointed to by 
the global variable DefVCBPtr. 


File Control Blocks 
eeeClick on the X-Ref button, and refer to Technical Note #87.¢e« 


Each time a file is opened, the file's directory entry is used to build a file 
control block in the file-control-block buffer, which contains information about 
all access paths. The file-control-block-buffer is a nonrelocatable block in the 
system heap; the first word contains the length of the buffer. 


The number of file control blocks is contained in the system startup information 
on a volume. With the 64K ROM, the standard number is 12 file control blocks on 
a Macintosh 128K and 48 file control blocks on the Macintosh 512K. With the 128K 
ROM, there's a standard of 40 file control blocks per volume. 


Each open fork of a file requires one access path. Two access paths are used for 
the system and application resource files (whose resource forks are always 
open). On hierarchical directory volumes, two access paths are also needed for 
the extents and catalog trees. You should keep such files in mind when 
calculating the number of files that can be opened by your application. 


Note: The size of the file-control-block buffer is determined by 
the system startup information stored on a volume. 


You can get information from the file control block allocated for an open file 
by calling the File Manager function PBGetFCBInfo. When you call PBGetFCBInfo, 
you'll use the following 12 additional fields after the standard eight fields in 
the parameter block record FCBPBRec: 
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ioRefNum: INTEGER; {path reference number} 


filler: INTEGER; {not used} 

ioFCBIndx: LONGINT; {FCB index} 

ioFCBFLUNm: LONGINT; {file number} 

ioFCBFlags: INTEGER; {flags} 

ioFCBStBLk: INTEGER; {first allocation block of file} 
ioFCBEOF: LONGINT; {logical end-of-file} 
ioFCBPLen: LONGINT; {physical end-of-file} 
ioFCBCrPs: LONGINT; {mark} 

ioFCBVRefNum: INTEGER; {volume reference number} 
LoFCBCLpSiz: LONGINT; {file clump size} 
ioFCBParID: LONGINT; {parent directory ID} 


FUNCTION PBGetFCBInfo (paramBlock: FCBPBPtr; async: BOOLEAN) : OSErr; 


Trap macro _GetFCBInfo 

Parameter block 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
<-- 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
<-> 24 ioRefNum word 
--> 28 ioFCBIndx long word 
<-- 32 ioFCBFLNm long word 
<-- 36 ioFCBFlags word 
<-- 38 ioFCBStBLk word 
<-- 40 ioFCBEOF long word 
<-- 44 ioFCBPLen long word 
<-- 48 ioFCBCrPs long word 
<-- 52 ioFCBVRefNum word 
<-- 54 ioFCBClLpSiz long word 
<-- 58 ioFCBParID long word 


PBGetFCBInfo returns information about the specified open file. If ioFCBIndx is 
positive, the File Manager returns information about the file whose file number 
is ioFCBIndx on the volume specified by ioVRefNum (which may contain a drive 
number, volume reference number, or working directory reference number). If 
ioVRefNum is 0, all open files are indexed; otherwise, only open files on the 
specified volume are indexed. 


If ioFCBIndx is 0, the File Manager returns information about the file whose 
access path is specified by ioRefNum. 


Assembly-language note: The global variable FCBSPtr points to the 
length word of the file-control-block buffer. 


Each file control block contains 94 bytes of information about an access path; 
Figure 28 shows its structure (using the assembly-language offsets). 
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64K ROM note: 


fcbFIN um flong word) 
fchMd RB yt (byte) 
fcbTypB yt (byte) 
fchSBlk (word) 


fcbEOF (long word) 
tcbPLen (lone ward) 


fcbCrPs flong word) 


fcbh¥ Pt (pointer) 
fchBfAdr (pointer) 


tcbFlPos (word) 


fcbClmpsize (long word) 
fchETCB Pt (long word) 
fcbExtRec (12 bytes) 
fcbF Type (long word) 
fcbCatPos (long word) 
febDixID (long word) 


fcbCHame (bytes) 


file number 

flags 

version number 

first allocation block of file 
logical end-of-file 

physical end-of-file 

mark 

pointer to volume control block 
pointer to access path buffer 
used intemally 

file clump size 

pointer ta B*-tree contol block 
first three file extents 

file's finder trpe bytes 

used intermally 

file's parent ID 


name of open file 


Figure 26-A File Control Block 
Figure 28-A File Control Block 


The structure of a file control block in the 64K ROM 


version of the File Manager is a subset of the above 
structure. The old file control block contained only 
the fields up to and including fcbFlPos. 


FCBMdRByt (which corresponds to ioFCBFlags in the parameter block for 


PBGetFCBInfo) contains flags that describe the status of the file, as follows: 


Bit Meaning 

0 Set if data can be written to the file 

1 Set if the entry describes a resource fork 

7 Set if the file has been changed since it was last flushed 
Warning: The size and structure of a file control block may be 
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different in future versions of Macintosh system software. 


The Drive Queue 

eeeClick on the X-Ref button, and refer to Technical Note #36.°¢ee¢ 

Disk drives connected to the Macintosh are opened when the system starts up, and 
information describing each is placed in the drive queue. This is a standard 
Operating System queue, and each entry in it has the following structure: 


TYPE DrvQEl = RECORD 


qLink: QElemPtr; {next queue entry} 

qType: INTEGER; {queue type} 

dQDrive: INTEGER; {drive number} 

dQRefNum: INTEGER; {driver reference number} 

dQFSID: INTEGER; {file-system identifier} 

dQgprvsz: INTEGER; {number of logical blocks on drive} 
dQDrvSz2: INTEGER; {additional field to handle large } 


{ drive size} 
END; 


QLink points to the next entry in the queue. If qlype is 0, this means the 
number of logical blocks on the drive is contained in the dQDrvSz field alone. 
If qlype is 1, both dQDrvSz and dQDrvSz2 are used to store the number of blocks; 
dqDrvSz2 contains the high-order word of this number and dQDrvSz contains the 
low-order word. 


DQDrive contains the drive number of the drive on which the volume is mounted; 
dQRefNum contains the driver reference number of the driver controlling the 
device on which the volume is mounted. DQFSID identifies the file system 
handling the volume in the drive; it's 0 for volumes handled by the File 
Manager, and nonzero for volumes handled by other file systems. 


Four bytes of flags precede each drive queue entry; they're accessible only from 
assembly Language. 


Assembly-language note: These bytes contain the following: 


Byte Contents 

0 Bit 7=1 if volume is locked 

1 0 if no disk in drive; 1 or 2 if disk 
in drive; 8 if nonejectable disk in drive; 
$FC-$FF if disk was ejected within last 1.5 
seconds; $48 if disk in drive is 
nonejectable but driver wants a call 

2 Used internally during system startup 

3 Bit 7=0 if disk is single-sided 


You can get a pointer to the header of the drive queue by calling the File 
Manager function GetDrvQHdr. 


FUNCTION GetDrvQHdr : QHdrPtr; [Not in ROM] 


GetDrvQHdr returns a pointer to the header of the drive queue. 
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Assembly-language note: The global variable DrvQHdr contains the 
header of the drive queue. 


The drive queue can support any number of drives, limited only by memory space. 


USING AN EXTERNAL FILE SYSTEM 


Due to the complexity of writing an external file system for the 128K ROM 
version of the File Manager, this subject is covered in a separate document. To 
receive a copy, write to: 


Developer Technical Support 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 75-3T 
Cupertino, CA 95014 
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SUMMARY OF THE FILE MANAGER 


Constants 
CONST 


{ Flags in file information used by the Finder } 


fOnDesk — eee Pe {set if file is on desktop (hierarchical volumes only)} 
fHasBundle = 8192; {set if file has a bundle} 

fInvisible = 16384; {set if file's icon is invisible} 

fTrash = -3; {file is in Trash window} 

fDesktop = -2; {file is on desktop} 

fDisk = @Q; {file is in disk window} 


{ Values for requesting read/write permission} 


fsCurPerm = 0; {whatever is currently allowed} 

fsRdPerm = 1; {request for read permission only} 
fsWrPerm = 2; {request for write permission only} 
fsRdWrPerm = 3: {request for exclusive read/write permission} 
fsRdWwrShPerm = 4; {request for shared read/write permission} 
{ Positioning modes } 

fsAtMark = 0; fat current mark} 

fsFromStart = 15; {set mark relative to beginning of file} 
fsFromLEOF =.2) {set mark relative to logical end-of-file} 
fsFromMark = 3; {set mark relative to current mark} 
rdVerify = 64; {add to above for read-verify} 


; Bits in vMAttrib about the volume 


bHasNewDesk .EQU 12 ;If set, all of the new desktop calls are 
; supported (for example, OpenDB, AddIco, 
; AddComment) . 

bHasMoveRename  .EQU 13 ;If set, MoveRename call supported. 

bHasCopyFile . EQU 14 ;If set, CopyFile call supported. 


_CopyFile is used in copy and duplicate 
operations if both source and 
destination volumes have same server 
address. 

If set, supports OpenDeny and 
_OpenRFDeny calls. For copy operations, 
source files are opened with enable 
read/deny write and destination files 
are opened enable write/deny read and 
write. 

bExtFSVol . EQU 16 ;If set, this volume is an external file 

; system volume. Disk init package will 
; not be called. Erase Disk menu item is 
; disabled. 


bHasOpenDeny .EQU 15 


. 
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bNoSysDir . EQU 17 ;If set, volume doesn't support a system 
; directory; no switch launch to this volume. 
bAccessCntl . EQU 18 ;If set, volume supports AppleTalk AFP 
; access control interfaces. The calls 
; GetLoginInfo, GetDirAccess, 
; SetDirAccess, MapID, and MapName are 
; supported. Special folder icons are 
; used. Access Privileges menu item is 
; enabled for disk and folder items. The 
; privileges field of GetCatInfo calls are 
; assumed to be valid. 
bNoBootBLlks .EQU 19 ;If set, no boot blocks on this volume-- 
; not a startup volume. SetStartup menu 
; item will be disabled; boot blocks will 
; not be copied during copy operations. 
bNoDeskItems . EQU 20 ;If set, no items may be places on the 
; Finder desktop 
bNoSwitchTo . EQU 25 ;If set, Finder will not switch launch to 
; any application on the volume. 
bTrshOffLine .EQU 26 ;If set, anytime volume goes offline, it 
; is zoomed to the Trash and unmounted 
bNoLclSync . EQU 27 ;If set, volume's modification date is not 
; set by any Finder action. 
bNoVNEdit .EQU 28 ;If set, volume name cannot be edited. 
bNoMiniFndr .EQU 29 ;If set, MiniFinder menu item is disabled. 
bLocalWList .EQU 30 ;If set, Finder uses the returned shared 
; volume handle for its local window list. 
bLimitFCBs . EQU 31 ;If set, Finder limits the number of FCBs 
; used during copies to 8 (instead of 16). 
Data Types 
TYPE 
FInfo = RECORD 
fdType: OSType; {file type} 
fdCreator: OSType; {file's creator} 
fdFlags: INTEGER; {flags} 
fdLocation: Point; {file's location} 
fdFldr: INTEGER {file's window} 
END; 
FXInfo = RECORD 
fdIconID: INTEGER; {icon ID} 
fdUnused: ARRAY[1..4] OF INTEGER; {reserved} 
fdComment: INTEGER; {comment ID} 
fdPutAway: LONGINT; {home directory ID} 
END; 
DInfo = RECORD 
frRect: Rect; {folder's rectangle} 
frFlags: INTEGER; {flags} 
frLocation: Point; {folder's location} 
frView: INTEGER; {folder's view} 
END; 
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DXInfo = RECORD 
frScroll: Point; {scroll position} 
frOpenChain: LONGINT; {directory ID chain of open folders} 
frUnused: INTEGER; {reserved} 
frComment: INTEGER; {comment ID} 
frPutAway: LONGINT; {directory ID} 
END; 
ParamBlkType = (ioParam, fileParam, volumeParam, cntrlParam) ; 
ParmBLkPtr = “ParamBlockRec; 
ParamBlockRec = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
ioNamePtr: StringPtr; {pathname} 
ioVRefNum: INTEGER; {volume reference number, drive number, } 
{ or working directory reference number} 
CASE ParamBlkType OF 
ioParam: 
(ioRefNum: INTEGER; {path reference number} 
ioVersNum: SignedByte; {version number} 
ioPermssn: SignedByte; {read/write permission} 
ioMisc: Ptr; {miscellaneous} 
ioBuffer: Ptr; {data buffer} 
ioReqCount: LONGINT; {requested number of bytes} 
ioActCount: LONGINT; factual number of bytes} 
ioPosMode: INTEGER; {positioning mode and newline character} 
ioPosOffset: LONGINT); {positioning offset} 
fileParam: 
(ioFRefNum: INTEGER; {path reference number} 
ioFVersNum: SignedByte; {version number} 
fillerl: SignedByte; {not used} 
ioFDirIndex: INTEGER; {index} 
ioFlAttrib: SignedByte; {file attributes} 
ioFlVersNum: SignedByte; {version number} 
ioFlFndrinfo: FInfo; {information used by the Finder} 
ioDirID: LONGINT; {directory ID or file number} 
ioFLStBLk: INTEGER; {first allocation block of data fork} 
ioFlLgLen: LONGINT; {logical end-of-file of data fork} 
ioFlPyLen: LONGINT; {physical end-of-file of data fork} 
ioFLRStBLk: INTEGER; {first allocation block of resource fork} 
ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} 
ioFLRPyLen: LONGINT; {physical end-of-file of resource fork} 
ioFlCrDat: LONGINT; {date and time of creation} 
ioFlMdDat: LONGINT); {date and time of Last modification} 
volumeParam: 
(filler2: LONGINT; {not used} 
ioVolIndex: INTEGER; {index} 
ioVCrDate: LONGINT; {date and time of initialization} 
LoVLSBkUp: LONGINT; {date and time of last modification} 
ioVAtrb: INTEGER; {volume attributes} 
ioVNmFls: INTEGER; {number of files in root directory} 
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ioVDirSt: INTEGER; {first block of directory} 


ioVBLLn: INTEGER; {length of directory in blocks} 
ioVNmMALBLks: INTEGER; {number of allocation blocks} 
ioVALBLkSiz: LONGINT; {size of allocation blocks} 
ioVCLpSiz: LONGINT; {number of bytes to allocate} 
ioALBLSt: INTEGER; {first block in volume block map} 
ioVNxtFNum: LONGINT; {next unused file number} 
ioVFrBlk: INTEGER) ; {number of unused allocation blocks} 
cntrlParam: 
j {used by Device Manager} 
END; 
HParmBlkPtr = “HParamBlockRec; 
HParamBlockRec = RECORD 
{12 byte header used by the file system} 
qLink: QElemPtr; 
qType: INTEGER; 
ioTrap: INTEGER; 
ioCmdAddr: Ptr; 
{common header to all variants} 
ioCompletion: ProcPtr; {completion routine, or NIL if none} 
ioResult: OSErr; {result code} 
ioNamePtr: StringPtr; {ptr to pathname} 
ioVRefNum: INTEGER; {volume refnum} 


{different components for the different type of parameter blocks} 
CASE ParamBlkType OF 


I0Param: 
(ioRefNum: INTEGER; {refNum for I/0 operation} 
ioVersNum: SignedByte; {version number} 
ioPermssn: SignedByte; {Open: permissions (byte) } 
ioMisc: Ptr; {HRename: new name} 
{ HOpen: optional ptr to buffer} 
ioBuffer: Ptr; {data buffer Ptr} 
ioReqCount: LONGINT ; {requested byte count} 
ioActCount: LONGINT; factual byte count completed} 
ioPosMode: INTEGER; {initial file positioning} 
ioPosOffset: LONGINT); {file position offset} 
FileParam: 
(ioFRefNum: INTEGER; {reference number} 
ioFVersNum: SignedByte; {version number, normally 0} 
fillerl: SignedByte; 
ioFDirIndex: INTEGER; {HGetFInfo directory index} 


ioFlAttrib: SignedByte; {HGetFInfo: in-use bit=7, lock bit=0} 
ioFlVersNum: SignedByte; {file version number returned by GetFInfoz} 


ioFlFndrinfo: Finfo; {information used by the Finder} 

ioDirID: LONGINT; {directory ID} 

ioFLStBLk: INTEGER; {start file block (0 if none)} 

ioFlLgLen: LONGINT; {logical length (EOF) } 

ioFlPyLen: LONGINT; {physical length} 

ioFLRStBLk: INTEGER; {start block rsrc fork} 

ioFlRLgLen: LONGINT; {file logical length rsrc fork} 

ioFLRPyLen: LONGINT; {file physical length rsrc fork} 

ioFlCrDat: LONGINT; {file creation date & time (32 bits in secs)} 

ioFlMdDat: LONGINT) ; {last modified date and time} 
volumeParam: 

(filler2: LONGINT; {not used} 
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ioVolIndex: INTEGER; {index} 


ioVCrDate: LONGINT; {date and time of initialization} 
ioVLsMod: LONGINT; {date and time of last modification} 
ioVAtrb: INTEGER; {volume attributes} 

ioVNmF 1s: INTEGER; {number of files in root directory} 
ioVBitMap: INTEGER; {first block of volume bit map} 
ioAllocPtr: INTEGER; {block at which next new file starts} 
ioVNmMALBLks: INTEGER; {number of allocation blocks} 
ioVALBLkSiz: LONGINT; {size of allocation blocks} 
ioVClpSiz: LONGINT; {number of bytes to allocate} 
ioALBLSt: INTEGER; {first block in volume block map} 
ioVNxtCNID: LONGINT; {next unused file number} 

ioVFrBlk: INTEGER; {number of unused allocation blocks} 
ioVSigWord: INTEGER; {volume signature} 

ioVDrvinfo: INTEGER; {drive number} 

ioVDRefNum: INTEGER; {driver reference number} 

ioVFSID: INTEGER; {file system handling this volume} 
ioVBkUp: LONGINT; {date and time of last backup} 
ioVSeqNum: INTEGER; {used internally} 

ioVWrCnt LONGINT; {volume write count} 

ioVFilCnt: LONGINT; {number of files on volume} 
ioVDirCnt: LONGINT; {number of directories on volume} 


ioVFndrinfo: ARRAY[1..8] OF LONGINT); {information used by the Finder} 
AccessParam: 


(filler3: INTEGER; 

ioDenyModes: INTEGER; {access rights data} 

filler4: INTEGER; 

fillers: Signed Byte; 

ioACUser: Signed Byte; {access rights for directory only} 

filler6: LONGINT; 

ioACOwnerID: LONGINT; {owner ID} 

ioACGroupID: LONGINT; {group ID} 

ioACAccess: LONGINT); {access rights} 
ObjParam: 

(filler7: INTEGER; 

io0bjType: INTEGER; {function code} 

ioObjNamePtr: Ptr; {ptr to returned creator/group name} 

ioObjID: LONGINT; {creator/group ID} 

ioReqCount: LONGINT; {size of buffer area} 

ioActCount: LONGINT); {length of vol parms data} 
CopyParam: 

(ioDstVRefNum: INTEGER; {destination vol identifier} 

fillers: INTEGER; 

ioNewName: Ptr; {ptr to destination pathname} 

ioCopyName: Ptr; {ptr to optional name} 

ioNewDirID: LONGINT); {destination directory ID} 
WDParam: 

(filler9: INTEGER; 

iowDIndex: INTEGER; 

ioWDProcID: LONGINT; 

iowDVRefNum: INTEGER; 

fillerl0: INTEGER; 

fillerll: LONGINT; 

fillerl2: LONGINT; 

fillerl3: LONGINT; 

iowDDirID: LONGINT) ; 
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END; {HParamBlockRec} 


CInfoType = (hfileInfo,dirInfo) ; 
CInfoPBPtr = “*CInfoPBRec; 
CInfoPBRec = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
ioNamePtr: StringPtr; {pathname} 
ioVRefNum: INTEGER; {volume reference number, drive number, or } 
{ working directory reference number} 
ioFRefNum: INTEGER; {path reference number} 
ioFVersNum: SignedByte; {version number} 
fillerl: SignedByte; {not used} 
ioFDirIndex: INTEGER; {index} 
ioFlAttrib: SignedByte; {file attributes} 
filler2: SignedByte; {not used} 
CASE CInfoType OF 
hFileInfo: 
(ioFlFndrinfo: FInfo; {information used by the Finder} 
ioDirID: LONGINT; {directory ID or file number} 
ioFLStBLk: INTEGER; {first allocation block of data fork} 
ioFlLgLen: LONGINT; {logical end-of-file of data fork} 
ioFlPyLen: LONGINT; {physical end-of-file of data fork} 
ioFLRStBLk: INTEGER; {first allocation block of resource fork} 
ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} 
ioFLRPyLen: LONGINT; {physical end-of-file of resource fork} 
ioFlCrDat: LONGINT; {date and time of creation} 
ioFlMdDat: LONGINT; {date and time of last modification} 
ioFlBkDat: LONGINT; {date and time of last backup} 
ioFlXFndrinfo: FXInfo; {additional information used by the Finder} 
ioFlParID: LONGINT; {file's parent directory ID (integer)} 
ioFlClpSiz: LONGINT) ; {file's clump size} 
dirInfo: 
(ioDrUsrwds: DIinfo; {information used by the Finder} 
ioDrDirID: LONGINT; {directory ID} 
ioDrNmFls: INTEGER; {number of files in directory} 
filler3: ARRAY[1..9] OF INTEGER; {not used} 
ioDrCrDat: LONGINT; {date and time of creation} 
ioDrMdDat: LONGINT; {date and time of last modification} 
ioDrBkDat: LONGINT; {date and time of last backup} 
ioDrFndriInfo: DXInfo; {additional information used by the Finder} 
ioDrParID: LONGINT) ; {directory's parent directory ID (integer) } 
END; 
CMovePBPtr = “CMovePBRec; 
CMovePBRec = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
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ioNamePtr: StringPtr; {pathname} 


ioVRefNum: INTEGER; {volume reference number, drive number, or } 
{ working directory reference number} 
fillerl: LONGINT; {not used} 
ioNewName: StringPtr; {name of new directory} 
filler2: LONGINT; {not used} 
ioNewDirID: LONGINT; {directory ID of new directory} 
filler3: ARRAY[1..2] OF LONGINT; {not used} 
ioDirID: LONGINT) ; {directory ID of current directory} 
END; 
WDPBPtr = “WDPBRec; 
WDPBRec = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
ioNamePtr: StringPtr; {pathname} 
ioVRefNum: INTEGER; {volume reference number, drive number, or } 
{ working directory reference number} 
fillerl: INTEGER; {not used} 
iowDIndex: INTEGER; {index} 
ioWDProcID: LONGINT; {working directory user identifier} 
iowWDVRefNum: INTEGER; {working directory's volume reference number} 
filler2: ARRAY[1..7] OF INTEGER; {not used} 
iowDDirID: LONGINT) ; {working directory's directory ID} 
END; 
FCBPBPtr = “FCBPBRec; 
FCBPBRec = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
ioTrap: INTEGER; {routine trap} 
ioCmdAddr: Ptr; {routine address} 
ioCompletion: ProcPtr; {completion routine} 
ioResult: OSErr; {result code} 
ioNamePtr: StringPtr; {pathname} 
ioVRefNum: INTEGER; {volume reference number, drive number, or } 
{ working directory reference number} 
ioRefNum: INTEGER; {path reference number} 
filler: INTEGER; {not used} 
ioFCBIndx: LONGINT; {FCB index} 
ioFCBFLUNm: LONGINT; {file number} 
ioFCBFlags: INTEGER; {flags } 
ioFCBStBLk: INTEGER; {first allocation block of file} 
ioFCBEOF: LONGINT; {logical end-of-file} 
ioFCBPLen: LONGINT; {physical end-of-file} 
ioFCBCrPs: LONGINT; {mark} 
ioFCBVRefNum: INTEGER; {volume reference number} 
LoFCBC1LpSiz: LONGINT; {file's clump size} 
ioFCBParID: LONGINT; {parent directory ID} 
END; 
VCB = RECORD 
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qLink: QElemPtr; {next queue entry} 


qType: INTEGER; {queue type} 

vcbFlags: INTEGER; {bit 15=1 if dirty} 

vcbSigWord: INTEGER; {$4244 for hierarchical, $D2D7 for flat} 
vcbCrDate: LONGINT; {date and time of initialization} 
vcbLsMod: LONGINT; {date and time of Last modification} 
vcbAtrb: INTEGER; {volume attributes} 

vcbNmF 1s: INTEGER; {number of files in directory} 
vcbVBMSt: INTEGER; {first block of volume bit map} 
vcbAllocPtr: INTEGER; {used internally} 

vcbNmALBLks: INTEGER; {number of allocation blocks} 
vcbALBLkSiz: LONGINT; {allocation block size} 

vcbClpSiz: LONGINT; {default clump size} 

vcbALBLSt: INTEGER; {first block in block map} 
VcCbNxtCNID: LONGINT; {next unused directory ID or file number} 
vcbFreeBks: INTEGER; {number of unused allocation blocks} 
vcbVN: STRING[27]; {volume name} 

vcbDrvNum: INTEGER; {drive number} 

vcbDRefNum: INTEGER; {driver reference number} 

vcbFSID: INTEGER; {file-system identifier} 

vcbVRefNum: INTEGER; {volume reference number} 

vcbMAdr: Ptr; {pointer to block map} 

vcbBufAdr: Ptr; {pointer to volume buffer} 

vcbMLen: INTEGER; {number of bytes in block map} 
vcbDirIndex: INTEGER; {used internally} 

vcbDirBLk: INTEGER; {used internally} 

vcbVolBkUp: LONGINT ; {date and time of last backup} 
vcbVSeqNum: INTEGER; {used internally} 

vcbWrCnt: LONGINT; {volume write count} 

vcbXTClpSiz: LONGINT; {clump size of extents tree file} 
vcbCTClpSiz: LONGINT; {clump size of catalog tree file} 
vcbNmRtDirs: INTEGER; {number of directories in root} 
vcbFilCnt: LONGINT; {number of files on volume} 
vcbDirCnt: LONGINT; {number of directories on volume} 


vcbFndriInfo: ARRAY[1..8] OF LONGINT; {information used by } 
{ the Finder} 


vcbVCSize: INTEGER; {used internally} 
vcbVBMCSiz: INTEGER; {used internally} 
vcbCtlCSiz: INTEGER; {used internally} 
VCbXTALBks: INTEGER; {size in blocks of extents tree file} 
vcbCTALBks: INTEGER; {size in blocks of catalog tree file} 
vcbXTRef: INTEGER; {path reference number for extents } 
{ tree file} 
vcbCTRef: INTEGER; {path reference number for catalog } 
{ tree file} 
vcbCtlBuf : Ptr; {pointer to extents and catalog } 
{ tree caches} 
vcbDirIDM: LONGINT; {directory last searched} 
vcbOffsM: INTEGER {offspring index at last search} 
END; 
DrvQEl = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
dQDrive: INTEGER; {drive number} 
dQRefNum: INTEGER; {driver reference number} 
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dQFSID: INTEGER; {file-system identifier} 

dQgprvsz: INTEGER; {number of logical blocks on drive} 

dQDrvSz2: INTEGER; {additional field to handle large } 
{ drive size} 


END; 


High-Level Routines 
Accessing Volumes 


FUNCTION GetVInfo (drvNum: INTEGER; volName: StringPtr; VAR vRefNum: INTEGER; 
VAR freeBytes: LONGINT) : OSErr; 

pathRefNum: INTEGER; VAR vRefNum: INTEGER) : OSErr; 
volName: StringPtr; VAR vRefNum: INTEGER) : OSErr; 
volName: StringPtr; vRefNum: INTEGER) : OSErr; 

volName: StringPtr; vRefNum: INTEGER) : OSErr; 

volName: StringPtr; vRefNum: INTEGER) : OSErr; 

volName: StringPtr; vRefNum: INTEGER) : OSErr; 


FUNCTION GetVRefNum 
FUNCTION GetVol 
FUNCTION SetVol 
FUNCTION FlushVol 
FUNCTION UnmountVol 
FUNCTION Eject 


RR 


Accessing Files 


FUNCTION FSOpen (fileName: Str255; vRefNum: INTEGER; 
VAR refNum: INTEGER) : OSErr; 
FUNCTION OpenRF (fileName: Str255; vRefNum: INTEGER; 
VAR refNum: INTEGER) : OSErr; 
refNum: INTEGER; VAR count: LONGINT; buffPtr: Ptr) : OSErr; 
refNum: INTEGER; VAR count: LONGINT; buffPtr: Ptr) : OSErr; 
refNum: INTEGER; VAR filePos: LONGINT) : OSErr; 
refNum: INTEGER; posMode: INTEGER; posOff: LONGINT) : OSErr; 
refNum: INTEGER; VAR LogEOF: LONGINT) : OSErr; 
refNum: INTEGER; logEOF: LONGINT) : OSErr; 
refNum: INTEGER; VAR count: LONGINT) : OSErr; 
refNum: INTEGER) : OSErr; 


FUNCTION FSRead 
FUNCTION FSWrite 
FUNCTION GetFPos 
FUNCTION SetFPos 
FUNCTION GetEOF 
FUNCTION SetEOF 
FUNCTION Allocate 
FUNCTION FSClose 


ee Ee eee 


Creating and Deleting Files 


FUNCTION Create (fileName: Str255; vRefNum: INTEGER; creator: OSType; 
fileType: OSType) : OSErr; 
FUNCTION FSDelete (fileName: Str255; vRefNum: INTEGER) : OSErr; 


Changing Information About Files 


FUNCTION GetFinfo (fileName: Str255; vRefNum: INTEGER; 
VAR fndrinfo: FInfo) : OSErr; 
FUNCTION SetFiInfo (fileName: Str255; vRefNum: INTEGER; 
fndrinfo: FInfo) : OSErr; 
FUNCTION SetFLock (fileName: Str255; vRefNum: INTEGER) : OSErr; 
FUNCTION RstFLock (fileName: Str255; vRefNum: INTEGER) : OSErr; 
FUNCTION Rename (oldName: Str255; vRefNum: INTEGER; newName: Str255) : OSErr; 


Low-Level Routines 
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Initializing the File I/O Queue 

PROCEDURE FInitQueue; 

FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr; 
<-- 16 ioResult word 
<-> 22 ioVRefNum word 


Accessing Volumes 


FUNCTION PBGetVInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

<-> 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 

--> 28 ioVolIndex word 

<-- 30 ioVCrDate long word 
<-- 34 ioVLsBkUp long word 
<-- 38 ioVAtrb word 

<-- 40 ioVNmFlLs word 

<-- 42 ioVDirSt word 

<-- 44 ioVBLLn word 

<-- 46 ioVNmMALBLks — word 

<-- 48 ioVALBLkSiz long word 
<-- 52 ioVClLpSiz long word 
<-- 56 ioALBLSt word 

<-- 58 ioVNxtFNum long word 
<-- 62 ioVFrBlk word 

FUNCTION PBHGetVInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 

--> 12 ioCompletion pointer 
<-- 16 ioResult word 

<-> 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 

--> 28 ioVolIndex word 

<-- 30 ioVCrDate long word 
<-- 34 ioVLsMod long word 
<-- 38 ioVAtrb word 

<-- 40 ioVNmFlLs word 

<2 42 ioVBitMap word 

<-- 44 ioVAlLlocPtr word 

<-- 46 ioVNmALBLks ~~ word 

<-- 48 ioVALBLkSiz long word 
<-- 52 ioVCLpSiz long word 
<-- 56 ioALBLSt word 

<-- 58 ioVNxtFNum long word 
<-- 62 ioVFrBlk word 

<-- 64 ioVSigWord word 

<-- 66 ioVDrvinfo word 

<-- 68 ioVDRefNum word 

<-- 70 ioVFSID word 

<-- 72 ioVBkUp long word 
<-- 76 ioVSeqNum word 

<-- 78 ioVWrCnt long word 
<-- 82 ioVFilCnt long word 
<-- 86 ioVDirCnt long word 
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nis 


FUNCTION 


FUNCTION 


--> 


90 ioVFndrinfo 32 bytes 

PBSetVInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

30 ioVCrDate long word 

34 ioVLsMod long word 

38 ioVAtrb word 

52 ioVCLpSiz long word 

72 ioVBkUp long word 

76 ioVSeqNum word 

90 ioVFndrinfo 32 bytes 

PBGetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

PBHGetVol (paramBlock: WDPBPtr; async: BOOLEAN): OsErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

28 iowDProcID long word 

32 ioWDVRefNum = word 

48 iowDDirID long word 

PBSetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

PBHSetVol (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

48 iowDDirID long word 

PBFlushVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

PBUnmountVol (paramBlock: ParmBlkPtr) : OSErr; 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

PBOffLine (paramBlock: ParmBlkPtr) : OSErr; 


12 


ioCompletion 


pointer 
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THE FILE 


<-- 16 ioResult 

--> 18 ioNamePtr 

--> 22 ioVRefNum 

FUNCTION PBEject (paramBlock: 

--> 12 ioCompletion 
<-- 16 ioResult 

--> 18 ioNamePtr 

--> 22 ioVRefNum 


Accessing Files 


word 
pointer 
word 


ParmBLkPtr) 
pointer 
word 
pointer 
word 


: OSErr; 


FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-- 24 ioRefNum word 
--> 26 ioVersNum byte 
--> 27 ioPermssn byte 
--> 28 ioMisc pointer 
FUNCTION PBHOpen (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-- 24 ioRefNum word 
--> 27 ioPermssn byte 
--> 28 ioMisc pointer 
--> 48 ioDirID long word 
FUNCTION PBOpenRF (paramBlock: ParmBLkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-- 24 ioRefNum word 
--> 26 ioVersNum byte 
--> 27 ioPermssn byte 
--> 28 ioMisc pointer 
FUNCTION PBHOpenRF (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
<-- 24 ioRefNum word 
--> 27 ioPermssn byte 
--> 28 ioMisc pointer 
--> 48 ioDirID long word 
FUNCTION PBLockRange (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 24 ioRefNum word 
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FUNCTION 


==> 


36 ioReqCount long word 

44 ioPosMode word 

46 ioPosOffset long word 

PBUnlockRange (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

36 ioReqCount long word 

44 ioPosMode word 

46 ioPosOffset long word 

PBRead (paramBlock: ParmBlLkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

32 ioBuffer pointer 

36 ioReqCount long word 

40 ioActCount long word 

44 ioPosMode word 

46 ioPosOffset long word 

PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

32 ioBuffer pointer 

36 ioReqCount long word 

40 ioActCount long word 

44 ioPosMode word 

46 ioPosOffset long word 

PBGetFPos (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

36 ioReqCount long word 

40 ioActCount long word 

44 ioPosMode word 

46 ioPosOffset long word 

PBSetFPos (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

44 ioPosMode word 

46 ioPosOffset long word 

PBGetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

28 ioMisc long word 

PBSetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


12 


ioCompletion 


pointer 
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Creating 


FUNCTION 


16 ioResult word 

24 ioRefNum word 

28 ioMisc long word 

PBALlocate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

36 ioReqCount long word 

40 ioActCount long word 

PBALlLocContig (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

36 ioReqCount long word 

40 ioActCount long word 

PBFlushFile (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

PBClose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 

12 ioCompletion pointer 

16 ioResult word 

24 ioRefNum word 

and Deleting Files and Directories 

PBCreate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

26 ioFVersNum byte 

PBHCreate (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

48 ioDirID long word 

PBDirCreate (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

48 ioDirID long word 

PBDelete (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 
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--> 26 ioFVersNum byte 


FUNCTION PBHDelete (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion pointer 
<: 5 16 ioResult word 

--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 

--> 48 ioDirID long word 


Changing Information About Files and Directories 


FUNCTION PBGetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion pointer 
<-- 16 ioResult word 

<-> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 

<-- 24 ioFRefNum word 

--> 26 ioFVersNum byte 

--> 28 ioFDirIndex word 

<-- 30 ioFlAttrib byte 

<-> 31 ioFlVersNum byte 

<s5 32 ioFlFndrinfo 16 bytes 
<-- 48 ioFlNum long word 
<-- 52 ioFlStBlk word 

<-- 54 ioFlLgLen long word 
<-- 58 ioFlPyLen long word 
<-- 62 ioFLRStBLk word 

<-- 64 ioFlRLgLen long word 
<-- 68 ioFlRPyLen long word 
<-- 72 ioFlCrDat long word 
<-- 76 ioFlMdDat long word 

FUNCTION PBHGetFInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 

--> 12 ioCompletion pointer 
ea 16 ioResult word 

<-> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 

<-- 24 ioFRefNum word 

--> 28 ioFDirIndex word 

<-- 30 ioFlAttrib byte 

<-- 32 ioFlFndrinfo 16 bytes 
<-> 48 ioDirID long word 
<-- 52 ioFlStBlk word 

<-- 54 ioFlLgLen long word 
<-- 58 ioFlPyLen long word 
<-- 62 ioFLRStBLk word 

<-- 64 ioFlRLgLen long word 
<-- 68 ioFlLRPyLen long word 
<-- 72 ioFlCrDat long word 
<-- 76 ioFlMdDat long word 

FUNCTION PBSetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 

--> 12 ioCompletion pointer 
<s5 16 ioResult word 

--> 18 ioNamePtr pointer 
225 22 ioVRefNum word 
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26 ioFVersNum byte 

32 ioFlFndrinfo 16 bytes 

72 ioFlCrDat long word 

76 ioFlMdDat long word 

PBHSetFInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

32 ioFlFndrinfo 16 bytes 

48 ioDirID long word 

72 ioFlCrDat long word 

76 ioFlLMdDat long word 

PBSetFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

26 ioFVersNum byte 

PBHSetFLock (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

48 ioDirID long word 

PBRstFLock (paramBlock: ParmBLkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

26 ioFVersNum byte 

PBHRstFLock (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

48 ioDirID long word 

PBSetFVers (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

26 ioVersNum byte 

28 ioMisc byte 

PBRename (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 
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o> 
--> 


FUNCTION 


26 ioVersNum byte 

28 ioMisc pointer 

PBHRename (paramBlock: HParmBlkPtr; async: BOOLEAN) 
12 ioCompletion pointer 

16 ioResult word 

18 ioNamePtr pointer 

22 ioVRefNum word 

28 ioMisc pointer 

48 ioDirID long word 


Hierarchical Directory Routines 


FUNCTION PBGetCatInfo (paramBlock: CInfoPBPtr; async: BOOLEAN) 


pointer 
word 
pointer 
word 

word 

word 

byte 

byte 

16 bytes 
16 bytes 
long word 
long word 
word 
word 
long 
long 
word 
long 
long 
long 
long 
long 
long 


word 
word 


word 
word 
word 
word 
word 
word 
long word 
long word 
16 bytes 
16 bytes 
long word 
long word 
long word 


PBSetCatInfo (paramBlock: CInfoPBPtr; async: BOOLEAN) 


12 ioCompletion 
16 ioResult 

18 ioNamePtr 

22 ioVRefNum 

24 ioFRefNum 

28 ioFDirIndex 
30 ioFlAttrib 
31 ioACUser 

32 ioFlFndrinfo 
32 ioDrUsrWds 
48 ioDirID 

48 ioDrDirID 

52 ioFlStBlk 

52 ioDrNmFls 

54 ioFlLgLen 

58 ioFlPyLen 

62 ioFLRStBlk 
64 ioFlRLgLen 
68 ioFlLRPyLen 
72 ioFlCrDat 

72 ioDrCrDat 

76 ioFlMdDat 

76 ioDrMdDat 

80 ioFlBkDat 

80 ioDrBkDat 

84 ioFlXFndrinfo 
84 ioDrFndriInfo 
100 ioFlParID 
100 ioDrParID 
104 =ioFlClpSiz 
12 ioCompletion 
16 ioResult 

18 ioNamePtr 

22 ioVRefNum 

30 ioFlAttrib 
32 ioFlFndrinfo 
32 ioDrUsrWds 
48 ioDirID 

48 ioDrDirID 

72 ioFlCrDat 


pointer 
word 
pointer 
word 

byte 

16 bytes 
16 bytes 
long word 
long word 
long word 


: OSErr; 


: OSErr; 


: OSErr; 
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--> 72 ioDrCrDat long word 
--> 76 ioFlMdDat long word 
--> 76 ioDrMdDat long word 
--> 80 ioFlBkDat long word 
--> 80 ioDrBkDat long word 
--> 84 ioFlXFndrinfo 16 bytes 
--> 84 ioDrFndrinfo 16 bytes 
--> 104 =ioFlClpSiz long word 
FUNCTION PBCatMove (paramBlock: CMovePBPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
--> 22 ioVRefNum word 
--> 28 ioNewName pointer 
--> 36 ioNewDirID long word 
--> 48 ioDirID long word 
Working Directory Routines 
FUNCTION PBOpenWD (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
--> 28 ioWDProcID long word 
--> 48 iowDDirID long word 
FUNCTION PBCloseWD (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
--> 22 ioVRefNum word 
FUNCTION PBGetWDInfo (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
<-- 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
--> 26 iowDIndex word 
<-> 28 ioWDProcID long word 
<-> 32 ioWDVRefNum = word 
<-- 48 iowDDirID long word 
Advanced Routines 
FUNCTION GetFSQHdr : QHdrPtr; [Not in ROM] 
FUNCTION GetVCBQHdr : QHdrPtr; [Not in ROM] 
FUNCTION GetDrvQHdr : QHdrPtr; [Not in ROM] 
FUNCTION PBGetFCBInfo (paramBlock: FCBPBPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion pointer 
<-- 16 ioResult word 
<-- 18 ioNamePtr pointer 
<-> 22 ioVRefNum word 
<-> 24 ioRefNum word 
--> 28 ioFCBIndx long word 


THE 


MANAG! 
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<-- 32 ioFCBFLNm long word 


<-- 36 ioFCBFlags word 
<-- 38 ioFCBStBlk word 
<-- 40 ioFCBEOF long word 
<-- 44 ioFCBPLen long word 
<-- 48 ioFCBCrPs long word 
<-- 52 ioFCBVRefNum word 
<-- 54 ioFCBClLpSiz long word 
<-- 58 ioFCBParID long word 


Shared Environment Routines 


FUNCTION PBHGetVolParms (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion long 
<s- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
<-- 32 ioBuffer long 
--> 36 ioReqCount long 
<-- 40 ioActCount long 
FUNCTION PBHGetLogInInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 22 ioVRefNum word 
<-- 26 io0bjType word 
<-- 28 ioObjNamePtr long 
FUNCTION PBHGetDirAccess (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
<-- 36 ioACOwnerID long 
<-- 40 ioACGroupID long 
<-- 44 ioACAccess long 
--> 48 ioDirID long 
FUNCTION PBHSetDirAccess (paramBlock: HParmBLkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 


--> 36 ioACOwnerID long 
> 40 ioACGroupID long 
--> 44 ioACAccess long 


--> 48 ioDirID long 
FUNCTION PBHMapID (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
--> 26 io0bjType word 
<-- 28 ioObjNamePtr long 
--> 32 io0bj ID long 
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FUNCTION PBHMapName (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 


--> 12 ioCompletion long 
Sirs 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
--> 28 ioObjNamePtr long 
--> 26 io0bjType word 
<-- 32 io0bj ID long 
FUNCTION PBHCopyFile (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
--> 24 ioDstVRefNum word 
--> 28 ioNewName long 
--> 32 ioCopyName long 
--> 36 ioNewDirID long 
--> 48 ioDirID long 
FUNCTION PBHMoveRename (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
--> 28 ioNewName long 
--> 32 ioBuffer long 
--> 36 ioNewDirID long 
--> 48 ioDirID long 
FUNCTION PBHOpenDeny (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
<s- 24 ioRefNum word 
--> 26 ioDenyModes __ word 
--> 48 ioDirID long 
FUNCTION PBHOpenRFDeny (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr; 
--> 12 ioCompletion long 
<-- 16 ioResult word 
--> 18 ioFileName long 
--> 22 ioVRefNum word 
<-- 24 ioRefNum word 
22> 26 ioDenyModes __ word 
--> 48 ioDirID long 
Result Codes 
Name Value Meaning 
badMDBErr —60 Master directory block is bad; must reinitialize 
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badMovErr 
bdNamErr 


dirFulErr 
dirNFErr 
dskFulErr 
dupFNErr 


eofErr 
extFSErr 


fBsyErr 


flcokdErr 
fnfErr 
fnOpnErr 
fsDSIntErr 
fsRnErr 
gfpErr 
ioErr 
memFullErr 
noErr 
noMacDskErr 
nsDrvErr 


nsvErr 
opWrErr 


paramErr 


permErr 
posErr 
rfNumErr 
tmfoErr 
tmwdoErr 
volOffLinErr 
volOnLinErr 
vLckdErr 
wrgVolTypErr 


wrPermErr 
wPrErr 
VolGoneErr 
AccessDenied 


DenyConflict 


NoMoreLocks 


RangeNotLocked 


RangeOverlap 


volume 

Attempted to move into offspring 

Bad file name or volume name (perhaps zero-length); 
attempt to move into a file 

File directory full 

Directory not found 

ALL allocation blocks on the volume are full 

A file with the specified name and version 

number already exists 

Logical end-of-file reached during read operation 
External file system; file-system identifier is 
nonzero, or path reference number is greater than 1024 
File is busy; one or more files are open; directory 
not empty or working directory control block is open 
File locked 

File not found 

File not open 

Internal file system error 

Problem during rename 

Error during GetFPos 

I/O error 

Not enough room in heap zone 

No error 

Volume Lacks Macintosh-format directory 

Specified drive number doesn't match any number 

in the drive queue 

Specified volume doesn't exist 

The read/write permission of only one access 

path to a file can allow writing 

Parameters don't specify an existing volume, and 
there's no default volume 

Attempt to open locked file for writing 

Attempt to position before start of file 

Reference number specifies nonexistent access path 
Too many files open 

Too many working directories open 

Volume not on-line 

Specified volume is already mounted and on-line 
Volume is locked by a software flag 

Attempt to do hierarchical operation on 
nonhierarchical volume 

Read/write permission doesn't allow writing 

Volume is locked by a hardware setting 

Connection to the server volume has been disconnected, 
but the VCB is still around and marked offline. 
The operation has failed because the user does not 
have the correct access to the file/folder. 

The operation has failed because the permission or 
deny mode conflicts with the mode in which the 
fork has already been opened. 

Byte range locking has failed because the 

server cannot lock any additional ranges. 

User has attempted to unlock a range that 

was not locked by this user. 

User attempted to lock some or all of a range 
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that is already 
locked. 


Assembly-Language Information 
Constants 


; Flags in file information used by the Finder 


fOnDesk .EQU 1 ;set if file is on desktop 

; (hierarchical volumes only) 
fHasBundle . EQU 13 sset if file has a bundle 
fInvisible . EQU 14 ‘set if file's icon is invisible 
fTrash . EQU -3 ‘file is in Trash window 
fDesktop . EQU -2 ;file is on desktop 
fDisk . EQU 0 ‘file is in disk window 


; Flags in trap words 
asnycTrpBit .EQU 10 ;set for an asynchronous call 


; Values for requesting read/write permission 


fsCurPerm .EQU 0 ;whatever is currently allowed 

fsRdPerm . EQU 1 ;request for read permission only 
fsWrPerm .EQU 2 ;request for write permission only 
fsRdWrPerm . EQU 3 ;request for exclusive read/write permission 
fsRdWrShPerm . EQU 4 ;request for shared read/write permission 
; Positioning modes 

fsAtMark .EQU 0 ;at current mark 

fsFromStart .EQU 1 ;set mark relative to beginning of file 
fsFromLEOF .EQU 2 ;set mark relative to logical end-of-file 
fsFromMark .EQU 3 ;set mark relative to current mark 
rdVerify . EQU 64 ;add to above for read-verify 


Structure of File Information Used by the Finder 


fdType File type (long) 

fdCreator File's creator (long) 

fdFlags Flags (word) 

fdLocation File's location (point; long) 

fdFldr File's window (word) 

fdIconID File's icon ID (word) 

fdUnused Reserved (8 bytes) 

fdComment File's comment ID (word) 

fdPutAway File's home directory ID (long word) 


Structure of Directory Information Used by the Finder 


frRect Folder's rectangle (8 bytes) 
frFlags Flags (word) 

frLocation Folder's location (point; long) 
frView Folder's view (word) 
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frScroll 
frOpenChain 
f rUnused 
frComment 
frPutAway 


Folder's scroll position (point; long) 
Directory ID chain of open folders (long word) 
Reserved (word) 

Folder's comment ID (word) 

Folders's home directory ID (long word) 


Standard Parameter Block Data Structure 


qLink 
qlype 
ioTrap 
ioCmdAddr 


ioCompletion 


ioResult 
ioFileName 
ioVNPtr 
ioVRefNum 


ioDrvNum 


Pointer to next queue entry 

Queue type (word) 

Routine trap (word) 

Routine address 

Address of completion routine 

Result code (word) 

Pointer to pathname (preceded by length byte) 
Pointer to volume name (preceded by length byte) 
Volume reference number or working directory 
reference number (word) 

Drive number (word) 


Structure of I/0 Parameter Block 


ioRefNum 
ioFileType 
ioPermssn 
ioNewName 
ioLEOF 
io0OwnBuf 
ioNewType 
ioBuf fer 
ioReqCount 
ioActCount 
ioPosMode 
ioPosOffset 
i0QElSize 


Path reference number (word) 

Version number (byte) 

Read/write permission (byte) 

Pointer to new pathname (preceded by length byte) 
Logical end-of-file for SetEOF (long) 

Pointer to access path buffer 

New version number for SetFilType (byte) 
Pointer to data buffer 

Requested number of bytes (long) 

Actual number of bytes (long) 

Positioning mode and newline character (word) 
Positioning offset (long) 

Size in bytes of I/O parameter block 


Structure of File Parameter Block 


ioRefNum 
ioFileType 
ioFDirIndex 
ioFlAttrib 
ioFFlType 
ioFlUsrwds 
ioDirID 
ioFFlNum 
ioFlLStBlk 
ioFlLgLen 
ioFlPyLen 
ioFLRStBlk 
ioFlRLgLen 
ioFlLRPyLen 
ioFlCrDat 
ioFlMdDat 
ioFQELSize 


Path reference number (word) 

Version number (byte) 

Directory index (word) 

File attributes (byte) 

Version number (byte) 

Information used by the Finder (16 bytes) 
Directory ID (long) 

File number (long) 

First allocation block of data fork (word) 
Logical end-of-file of data fork (long) 
Physical end-of-file of data fork (long) 

First allocation block of resource fork (word) 
Logical end-of-file of resource fork (long) 
Physical end-of-file of resource fork (long) 
Date and time of creation (long) 

Date and time of last modification (long) 

Size in bytes of file information parameter block 
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Structure of Volume Information Parameter Block (Flat Directory) 


ioVolIndex 
ioVCrDate 
LoVLsBkUp 
ioVAtrb 
ioVNmFls 
ioVDirSt 
ioVBLLn 
ioVNmALBLks 
ioVALBLkSiz 
ioVCLpSiz 
ioALBLSt 
ioVNxtFNum 
ioVFrBlk 
ioVQElLSize 


Volume index (word) 

Date and time of initialization (long) 

Date and time of last modification (long) 

Volume attributes; bit 15=1 if volume locked (word) 
Number of files in directory (word) 

First block of directory (word) 

Length of directory in blocks (word) 

Number of allocation blocks on volume (word) 

Size of allocation blocks (long) 

Number of bytes to allocate (long) 

First block in block map (word) 

Next unused file number (long) 

Number of unused allocation blocks (word) 

Size in bytes of volume information parameter block 


Structure of Volume Information Parameter Block (Hierarchical Directory) 


ioVolIndex 
ioVCrDate 
ioVLsMod 
ioVAtrb 
ioVNmFls 
ioVCBVBMSt 
ioVNmALBLks 
ioVALBLkSiz 
ioVCLpSiz 
ioALBLSt 
ioVNxtCNID 
ioVFrBlk 
ioVSigWord 
ioVDrvinfo 
ioVDRefNum 
ioVFSID 
ioVBkUp 
ioVWrCnt 
ioVFilCnt 
ioVDirCnt 
ioVFndrinfo 
ioHVQElSize 


Volume index (word) 

Date and time of initialization (long) 
Date and time of last modification (long) 
Volume attributes (word) 

Number of files in directory (word) 

First block of volume bit map (word) 
Number of allocation blocks (word) 

Size of allocation blocks (long) 

Default clump size (long) 

First block in block map (word) 

Next unused node ID (long) 

Number of unused allocation blocks (word) 
Volume signature (word) 

Drive number (word) 

Driver reference number (word) 
File-system identifier (word) 

Date and time of last backup (long) 
Volume write count (long) 

Number of files on volume (long) 

Number of directories on volume (long) 
Information used by the Finder (32 bytes) 
Size in bytes of hierarchical volume 
information parameter block 


Structure of Catalog Information Parameter Block (Files) 


ioRefNum 
ioFileType 
ioFDirIndex 
ioFlAttrib 
ioFlUsrwWds 
ioFFlUNum 
ioFlStBlk 
ioFlLgLen 
ioFlPyLen 
ioFLRStBlk 
ioFlRLgLen 


Path reference number (word) 

Version number (byte) 

Directory index (word) 

File attributes 

Information used by the Finder (16 bytes) 
File number (long) 

First allocation block of data fork (word) 
Logical end-of-file of data fork (long) 
Physical end-of-file of data fork (long) 
First allocation block of resource fork (word) 
Logical end-of-file of resource fork (long) 
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ioFlLRPyLen Physical end-of-file of resource fork (long) 


ioFlCrDat Date and time of creation (long) 

ioFlMdDat Date and time of last modification (long) 

ioFlBkDat Date and time of last backup (long) 

ioFlXFndrinfo Additional information used by the Finder (16 bytes) 
ioFlParID File parent directory ID (long) 

ioFlLClpSiz File's clump size (long) 


Structure of Catalog Information Parameter Block (Directories) 


ioRefNum Path reference number (word) 

ioFDirIndex Catalog index (word) 

ioFlAttrib File attributes 

ioDrUsrWds Information used by the Finder (16 bytes) 
ioDrDirID Directory ID (long) 

ioDrNmFls Number of files in directory (word) 
ioDrCrDat Date and time of creation (long) 
ioDrMdDat Date and time of last modification (long) 
ioDrBkDat Date and time of last backup (long) 
ioDrFndrinfo Additional information used by the Finder (16 bytes) 
ioDrParID Directory's parent directory ID (long) 


Structure of Catalog Move Parameter Block 


ioNewName Pointer to name of new directory (preceded by length byte) 
ioNewDirID Directory ID of new directory (long) 
ioDirID Directory ID of current directory (long) 


Structure of Working Directory Parameter Block 


iowDIndex Working directory index (word) 

iowDProcID Working directory's user identifier (long) 
ioWDVRefNum Working directory's volume reference number (word) 
iowDDirID Working directory's directory ID (long) 


Structure of File Control Block Information Parameter Block 


ioFCBIndx FCB index (long) 

ioFCBFLNm File number (long) 

ioFCBFlags Flags (word) 

ioFCBStBlk First allocation block of file (word) 
ioFCBEOF Logical end-of-file (long) 

ioFCBPLen Physical end-of-file (long) 

ioFCBCrPs Mark (long) 

ioFCBVRefNum Volume reference number (word) 
ioFCBCLpSiz File's clump size (long) 

ioFCBParID Parent directory ID (long) 


Volume Information Data Structure (Flat Directory) 


drSigWord Always $D2D7 (word) 

drCrDate Date and time of initialization (long) 
drLsBkUp Date and time of last modification (long) 
drAtrb Volume attributes (word) 

drNmFls Number of files in directory (word) 
drDirSt First block of directory (word) 
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drBlLn 
drNmAlLBlks 
drAlBLlkSiz 
drClpSiz 
drAlBLSt 
drNxtFNum 
drFreeBks 
drVN 


Length of directory in blocks (word) 

Number of allocation blocks (word) 

Allocation block size (long) 

Number of bytes to allocate (long) 

First allocation block in block map (word) 
Next unused file number (long) 

Number of unused allocation blocks (word) 
Volume name preceded by length byte (28 bytes) 


Volume Information Data Structure (Hierarchical Directory) 


drSigwWord 
drCrDate 
drLsMod 
drAtrb 
drNmFls 
drVBMSt 
drNmAlLBlLks 
drAlBlkSiz 
drClpSiz 
drAlBLSt 
drNxtCNID 
drFreeBks 
drVN 
drVolBkUp 
drwrCnt 
drXTClpSiz 
drCTClpSize 
drNmRtDirs 
drFitCnt 
drDirCnt 
drFndrinfo 
drXTFlSize 
drXTExtRec 
drCTFlSize 
drCTExtRec 


Always $4244 (word) 

Date and time of initialization (long) 

Date and time of last modification (long) 
Volume attributes (word) 

Number of files in directory (word) 

First block of volume bit map (word) 

Number of allocation blocks (word) 

Allocation block size (long) 

Default clump size (long) 

First block in block map (word) 

Next unused directory ID (long) 

Number of unused allocation blocks (word) 
Volume name (28 bytes) 

Date and time of last backup (long) 

Volume write count (long) 

Clump size of extents tree file (long) 

Clump size of catalog tree file (long) 

Number of directories in root (word) 

Number of files on volume (long) 

Number of directories on volume (long) 
Information used by the Finder (32 bytes) 
Length of extents tree (LEOF and PEOF) (long) 
Extent record for extents tree file (12 bytes) 
Length of catalog tree file (LEOF and PEOF) (long) 
First extent record for catalog tree file (12 bytes) 


File Directory Entry Data Structure (Flat Directory) 


flFlags 
flTyp 
flUsrWds 
fLFLNum 
FLStBLk 
flLgLen 
flPyLen 
FLRStBLk 
fLRLgLen 
fLRPyLen 
flCrDat 
f1MdDat 
flNam 


Bit 7=1 if entry used; bit 0=1 if file locked (byte) 
Version number (byte) 

Information used by the Finder (16 bytes) 

File number (long) 

First allocation block of data fork (word) 
Logical end-of-file of data fork (long) 
Physical end-of-file of data fork (long) 

First allocation block of resource fork (word) 
Logical end-of-file of resource fork (long) 
Physical end-of-file of resource fork (long) 
Date and time file of creation (long) 

Date and time of last modification (long) 

File name preceded by length byte 


Extents Key Data Structure (Hierarchical Directory) 


xkrKeyLen 


Key length (byte) 
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xkrFkType 
xkrFNum 
xkrFABN 


$00 for data fork; $FF for resource fork (byte) 
File number (long) 
Allocation block number within file (word) 


Catalog Key Data Structure (Hierarchical Directory) 


ckrKeyLen 
ckrParID 
ckrCName 


Key length (byte) 
Parent ID (long) 
File or directory name preceded by length byte 


File Record Data Structure (Hierarchical Directory) 


cdrType 
filFlags 
filTyp 
filUsrWds 
FilFlNum 
filStBlk 
filLgLen 
filPyLen 
filRStBlk 
filRLgLen 
filRPyLen 
filCrDat 
filMdDat 
filBkDat 
filFndrinfo 
filClpSize 
filExtRec 
filRExtRec 


Always 2 for file records (byte) 

Bit 7=1 if entry used; bit 0=1 if file locked (byte) 
Version number (byte) 

Information used by the Finder (16 bytes) 

File number (long) 

First allocation block of data fork (word) 

Logical end-of-file of data fork (long) 

Physical end-of-file of data fork (long) 

First allocation block of resource fork (word) 
Logical end-of-file of resource fork (long) 

Physical end-of-file of resource fork (long) 

Date and time of creation (long) 

Date and time of last modification (long) 

Date and time of last backup (long) 

Additional information used by the Finder (16 bytes) 
File's clump size (word) 

First extent record for data fork (12 bytes) 

First extent record for resource fork (12 bytes) 


Directory Record Data Structure (Hierarchical Directory) 


cdrType 
dirFlags 
dirVal 
dirDirID 
dirCrDat 
dirMdDat 
dirBkDat 
dirUsrinfo 
dirFndrinfo 


Always 1 for directory records (byte) 

Flags (word) 

Valence (word) 

Directory ID (long) 

Date and time of creation (long) 

Date and time of last modification (long) 

Date and time of last backup (long) 

Information used by the Finder (16 bytes) 

Additional information used by the Finder (16 bytes) 


Thread Record Data Structure (Hierarchical Directory) 


cdrType 
thdParID 
thdCName 


Always 3 for thread records (byte) 
Parent ID of associated directory (long) 
Name of associated directory preceded by length byte 


Volume Control Block Data Structure (Flat Directory) 


qLink 
qType 
vcbFlags 
vcbSigWord 
vcbCrDate 


Pointer to next queue entry 

Queue type (word) 

Bit 15=1 if volume control block is dirty (word) 
Always $D2D7 (word) 

Date and time of initialization (word) 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 « Apple Computer 
THE FILE MANAGER e 145 of 150 


vcbLsBkUp 
vcbAtrb 
vcbNmFlLs 
vcbDirSt 
vcbBLLn 
vcbNmBlks 
vcbALBLkSiz 
vcbClpSiz 
vcbALBLSt 
vcbNxtFNum 
vcbFreeBks 
vcbVN 
vcbDrvNum 
vcbDRefNum 
vcbFSID 
vcbVRefNum 
vcbMAdr 
vcbBufAdr 
vcbMLen 


Date and time of last modification (long) 
Volume attributes (word) 

Number of files in directory (word) 

First block of directory (word) 

Length of directory in blocks (word) 
Number of allocation blocks (word) 
Allocation block size (long) 

Number of bytes to allocate (long) 

First allocation block in block map (word) 
Next unused file number (long) 

Number of unused allocation blocks (word) 
Volume name preceded by length byte (28 bytes) 
Drive number (word) 

Driver reference number (word) 

File-system identifier (word) 

Volume reference number (word) 

Pointer to block map 

Pointer to volume buffer 

Number of bytes in block map (word) 


Volume Control Block Data Structure (Hierarchical Directory) 


qLink 

qType 
vcbFlags 
vcbSigWord 
vcbCrDate 
vcbLsMod 
vcbAtrb 
vcbNmFls 
vcbVBMSt 
vcbNmALBLks 
vcbALBLkSiz 
vcbClpSiz 
vcbALBLSt 
vcbNxtCNID 
vcbFreeBks 
vcbVN 
vcbDrvNum 
vcbDRefNum 
vcbFSID 
vcbVRefNum 
vcbMAdr 
vcbBufAdr 
vcbMLen 
vcbVoLBkUp 
vcbVSeqNum 
vcbWrCnt 
vcbXTClpSiz 
vcbCTClpSiz 
vcbNmRtDirs 
vcbFilCnt 
vcbDirCnt 
vcbFndriInfo 
vcbXTALBks 
vcbCTALBks 


Pointer to next queue entry 

Queue type (word) 

Bit 15=1 if volume control block is dirty (word) 
$4244 for hierarchical, $D2D7 for flat (word) 
Date and time of initialization (word) 
Date and time of last modification (long) 
Volume attributes (word) 

Number of files in directory (word) 

First block of volume bit map (word) 
Number of allocation blocks (word) 
Allocation block size (long) 

Default clump size (long) 

First block in bit map (word) 

Next unused node ID (long) 

Number of unused allocation blocks (word) 
Volume name preceded by length byte (28 bytes) 
Drive number (word) 

Driver reference number (word) 
File-system identifier (word) 

Volume reference number (word) 

Pointer to block map 

Pointer to volume buffer 

Number of bytes in block map (word) 

Date and time of last backup (long) 

Index of volume in backup set (word) 
Volume write count (long) 

Clump size of extents tree file (long) 
Clump size of catalog tree file (long) 
Number of directories in root (word) 
Number of files on volume (long) 

Number of directories on volume (long) 
Information used by the Finder (32 bytes) 
Size in blocks of extents tree file (word) 
Size in blocks of catalog tree file (word) 
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vcbXTRef Path reference number for extents tree file (word) 
vcbCTRef Path reference number for catalog tree file (word) 


vcbCtlBuf Pointer to extents and catalog tree caches (long) 
vcbDirIDM Directory last searched (long) 
vcbOffsM Offspring index at last search (word) 


File Control Block Data Structure (Flat Directory) 


fcbFlNum File number (long) 

fcbMdRByt Flags (byte) 

fcbTypByt Version number (byte) 

fcbSBLk First allocation block of file (word) 
FcbEOF Logical end-of-file (long) 

fcbPLen Physical end-of-file (long) 

fcbCrPs Mark (long) 

fcbVPtr Pointer to volume control block (long) 
fcbBfAdr Pointer to access path buffer (long) 


File Control Block Data Structure (Hierarchical Directory) 


fcbFlNum File number (long) 

FcbMdRByt Flags (byte) 

fcbTypByt Version number (byte) 

fcbSBLk First allocation block of file (word) 
FcbEOF Logical end-of-file (long) 

fcbPLen Physical end-of-file (long) 

fcbCrPs Mark (long) 

fcbVPtr Pointer to volume control block (long) 
fcbBfAdr Pointer to access path buffer (long) 
fcbClmpSize File's clump size (long) 

fcbBTCBPtr Pointer to B*-tree control block (long) 
FcbExtRec First three file extents (12 bytes) 
fcbFType File's four Finder type bytes (long) 
fcbDirID File's parent ID (long) 

fcbCName Name of open file, preceded by length byte (32 bytes) 


Drive Queue Entry Data Structure 


qLink Pointer to next queue entry 

qType Queue type (word) 

dQDrive Drive number (word) 

dQRefNum Driver reference number (word) 

dQFSID File-system identifier (word) 

dQDrvSz Number of logical blocks on drive (word) 

dQDrvSz2 Additional field to handle large drive size (word) 


Macro Names 


Pascal name 


FInitQueue 
PBMountVol 
PBGetVInfo 
PBHGetVInfo 
PBSetVInfo 
PBGetVol 


Macro name 


_InitQueue 
_MountVol 
_GetVolInfo 
_HGetVInfo 
_SetVolInfo 
_GetVol 


THE 
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PBHGetVol _HGetVol 


PBSetVol _SetVol 
PBHSetVol _HSetVol 
PBFlushVol _FlushVolt 
PBUnmountVol _UnmountVol 
PBOffLine _OffLine 
PBEject _Eject 
PBOpen _ Open 
PBHOpen _HOpen 
PBOpenRF _OpenRF 
PBHOpenRF _HOpenRF 
PBLockRange _LockRng 
PBUnlockRange _UnlockRng 
PBRead _Read 
PBWrite _Write 
PBGetFPos _GetFPos 
PBSetFPos _SetFPos 
PBGetEOF _GetEOF 
PBSetEOF _SetEOF 
PBALlocate _Allocate 
PBALlocContig _AllocContig 
PBFlushFile _FlushFile 
PBClose _Close 
PBCreate _Create 
PBHCreate _HCreate 
PBDirCreate _DirCreate 
PBGetFInfo _GetFileInfo 
PBHGetFInfo _HGetFileInfo 
PBSetFInfo _SetFileInfo 
PBHSetFInfo _HSetFileInfo 
PBSetFLock _SetFilLock 
PBHSet FLock _HSetFLock 
PBRstFLock _RstFilLock 
PBHRstFLock _HRstFLock 
PBSetFVers _SetFilType 
PBRename _Rename 
PBHRename _HRename 
PBDelete _Delete 
PBHDelete _HDelete 
PBSetCatInfo _SetCatInfo 
PBCatMove _CatMove 
PBOpenWD _OpenwD 
PBCloseWD _ClosewD 
PBGetwDInfo _GetwWDInfo 
PBGetFCBInfo _GetFCBInfo 


Shared Environment Macros 


Pascal Name Macro Name Call Number 
PBGetCatInfo _GetCatInfo $09 
PBHGetVolParms _GetVolParms $30 


PBHGetLogInIinfo _GetLogInInfo $31 
PBHGetDirAccess _GetDirAccess $32 
PBHSetDirAccess _SetDirAccess $33 
PBHMapID _MapID $34 
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PBHMapName _MapName $35 


PBHCopyFile _CopyFile $36 
PBHMoveRename _MoveRename $37 
PBHOpenDeny _OpenDeny $38 
PBHOpenRFDeny _OpenRFDeny $39 


Special Macro Name 


_HFSDispatch 

Variables 

BootDrive Working directory reference number for system 
startup volume (word) 

FSQHdr File I/0 queue header (10 bytes) 

VCBQHdr Volume-control-block queue header (10 bytes) 

DefVCBPtr Pointer to default volume control block 

FCBSPtr Pointer to file-control-block buffer 

DrvQHdr Drive queue header (10 bytes) 

ToEXxtFS Pointer to external file system 

FSFCBLen Size of a file control block; on 64K ROM contains —1 (word) 
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Further Reference: 


AppleTalk Manager 
Device Manager 
Standard File Package 


Technical 
Technical 
Technical 
Technical 
Technical 
Technical 
Technical 
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